@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/recipes/catalog.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "./catalog.schema.json",
+  "catalogVersion": 1,
+  "description": "Initial semantic executable catalog (E1 tasks 1.2-1.3), classified by source-shape inspection of the @thorprovider/blocks prop contracts and the view templates. Scope: every slot the curated MVP views (home, product, category, checkout, account) render by default, covering both the selectable archetype slots declared by recipes/archetypes.json and the nested default slots that have no archetype (category.productCard, checkout.confirmation) so no legacy default support is dropped. The account view (change: storefront-customer-auth) declares the login/register slots: LoginPage1/SignUpPage1 are executable while LoginPage2 is held for its divergent callback contract. A variant is `executable` only when the slot's canonical data shape can feed its block props without a prop bridge and without inventing data; every other non-default variant is `held` with the specific reason. The one executable non-default swap is home.benefits Feature1 -> Feature2 (identical item contract, no bridge). user-panel (non-MVP view) is outside this initial catalog scope. E2 task 6.1 declares the base listing slot category.filter CategoryFilter2 as the single controlled listing (dataShape `CatalogQuery & CatalogResults`, state controlled) with the search/filter controls contributed by the logical mounts category.search / category.filters (no second block). Source-shape compatibility is not end-to-end backend behavior proof: the render is executable, but the category.search.apply / category.filter.apply actions remain held under the capability catalog (owner: storefront-catalog-search-filters, E2) until a real runtime proof. The `capabilities` map declares those operational capabilities with their requirements and verification state; E1 declares the held category.filter.apply action, E2 adds the held category.search.apply action and the held category.price.range capability that gates the category-filters showPrice option; no capability is claimed verified.",
+  "slots": {
+    "home.hero": {
+      "default": "StorefrontHero1",
+      "variants": {
+        "StorefrontHero1": {
+          "status": "executable",
+          "block": "StorefrontHero",
+          "dataShape": "FeaturedProduct[]",
+          "events": ["addToCart", "buyNow", "selectColor"],
+          "state": "uncontrolled",
+          "requirements": ["heroProducts"]
+        },
+        "StorefrontHero2": {
+          "status": "held",
+          "reason": "block requires a product with reviews/trending/tag and emits a search event; the canonical FeaturedProduct shape carries rating/reviewCount but not trending/tag, and no verified prop bridge exists",
+          "block": "StorefrontHero",
+          "dataShape": "StorefrontHero2FeaturedProduct[]",
+          "events": ["search", "productClick"],
+          "state": "uncontrolled",
+          "requirements": ["heroProducts"]
+        },
+        "StorefrontHero5": {
+          "status": "held",
+          "reason": "featuredDeals[].description is absent from the canonical product shape and Department.count would require inventing counts; no truthful prop bridge can be derived from source",
+          "block": "StorefrontHero",
+          "dataShape": "FeaturedDeal[] & Department[]",
+          "events": ["departmentClick", "shopNow", "locateStores"],
+          "state": "uncontrolled",
+          "requirements": ["featuredDeals", "departments"]
+        },
+        "StorefrontHero6": {
+          "status": "held",
+          "reason": "block requires deals with discount/endTime and categories with a required count; the canonical shape supplies neither without invention and no verified prop bridge exists",
+          "block": "StorefrontHero",
+          "dataShape": "HeroDeal[] & HeroCategory[]",
+          "events": ["shopNow", "categoryClick"],
+          "state": "uncontrolled",
+          "requirements": ["deals", "categories"]
+        }
+      }
+    },
+    "home.benefits": {
+      "default": "Feature1",
+      "variants": {
+        "Feature1": {
+          "status": "executable",
+          "block": "Feature",
+          "dataShape": "BenefitsItem[]",
+          "events": ["ctaClick", "learnMore"],
+          "state": "uncontrolled",
+          "requirements": []
+        },
+        "Feature2": {
+          "status": "executable",
+          "block": "Feature",
+          "dataShape": "BenefitsItem[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": []
+        }
+      }
+    },
+    "home.categories": {
+      "default": "ProductCategory2",
+      "variants": {
+        "ProductCategory2": {
+          "status": "executable",
+          "block": "CategoryCards",
+          "dataShape": "CategoryCard[]",
+          "events": ["browse"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory1": {
+          "status": "held",
+          "reason": "block requires categories with a subtitle and a named icon, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory1Category[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory4": {
+          "status": "held",
+          "reason": "block requires categories with title/icon/customers/products/avatarImages, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory4Category[]",
+          "events": ["categoryClick"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory5": {
+          "status": "held",
+          "reason": "block requires categories with subcategories and a required itemCount plus a search control, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory5Category[]",
+          "events": ["browse", "viewAll"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        }
+      }
+    },
+    "product.overview": {
+      "default": "ProductOverview1",
+      "variants": {
+        "ProductOverview1": {
+          "status": "executable",
+          "block": "ProductOverview",
+          "dataShape": "ProductDetailProduct",
+          "events": ["selectVariant", "quantityChange", "addToCart", "toggleWishlist"],
+          "state": "controlled",
+          "requirements": ["selectedProduct", "selectedVariantId"]
+        },
+        "ProductOverview2": {
+          "status": "held",
+          "reason": "block requires a product with brand/sku/sizes/colors and wishlist events, a shape the canonical ProductDetailProduct does not supply; no verified prop bridge exists",
+          "block": "ProductOverview",
+          "dataShape": "ProductOverview2Product",
+          "events": ["addToCart", "toggleWishlist"],
+          "state": "uncontrolled",
+          "requirements": ["selectedProduct"]
+        },
+        "ProductOverview5": {
+          "status": "held",
+          "reason": "block requires specifications/features/mainImages/galleryImages/userReviews, a shape the canonical ProductDetailProduct does not supply; no verified prop bridge exists",
+          "block": "ProductOverview",
+          "dataShape": "ProductOverview5Product",
+          "events": ["addToCart", "toggleWishlist"],
+          "state": "uncontrolled",
+          "requirements": ["selectedProduct"]
+        }
+      }
+    },
+    "product.reviews": {
+      "default": "ReviewRating1",
+      "variants": {
+        "ReviewRating1": {
+          "status": "executable",
+          "block": "Reviews",
+          "dataShape": "Review[]",
+          "events": ["toggleReviewLike", "submitReview"],
+          "state": "uncontrolled",
+          "requirements": ["productReviews"]
+        },
+        "ReviewRating2": {
+          "status": "held",
+          "reason": "block requires an aggregate averageRating/ratingDistribution and carousel controls the canonical Review[] shape does not supply; no verified prop bridge exists",
+          "block": "Reviews",
+          "dataShape": "Review[] & RatingSummary",
+          "events": ["like", "comment"],
+          "state": "uncontrolled",
+          "requirements": ["productReviews"]
+        }
+      }
+    },
+    "category.filter": {
+      "default": "CategoryFilter2",
+      "variants": {
+        "CategoryFilter2": {
+          "status": "executable",
+          "block": "CategoryFilter",
+          "dataShape": "CatalogQuery & CatalogResults",
+          "events": [
+            "productClick",
+            "pageChange",
+            "pageSizeChange",
+            "sortChange",
+            "filterChange",
+            "searchChange",
+            "clearFilters",
+            "repair",
+            "retry",
+            "removeFilter"
+          ],
+          "state": "controlled",
+          "requirements": ["categoryProducts", "categoryQuery", "facetSupport"]
+        },
+        "CategoryFilter1": {
+          "status": "held",
+          "reason": "block requires categories/priceRanges/sortOptions with counts the canonical CardProduct[] listing does not supply; no verified prop bridge exists",
+          "block": "CategoryFilter",
+          "dataShape": "CategoryFilter1Filters",
+          "events": ["filterChange"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "CategoryFilter4": {
+          "status": "held",
+          "reason": "block requires an advanced facets contract (modelTypes/rangeBands/frameSizes/colourways/features) the canonical listing does not supply; no verified prop bridge exists",
+          "block": "CategoryFilter",
+          "dataShape": "CategoryFilter4Facets",
+          "events": ["filterChange"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        }
+      }
+    },
+    "category.productCard": {
+      "default": "ProductCard1",
+      "variants": {
+        "ProductCard1": {
+          "status": "executable",
+          "block": "ProductCard",
+          "dataShape": "CardProduct[]",
+          "events": ["addToCart", "openProduct"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard2": {
+          "status": "held",
+          "reason": "block requires a product with a required rating, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard2Product[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard3": {
+          "status": "held",
+          "reason": "block requires a product with subtitle/originalPrice/reviewCount/discountPercentage and a badge, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard3Product[]",
+          "events": ["toggleWishlist", "viewSimilar", "productClick"],
+          "state": "controlled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard5": {
+          "status": "held",
+          "reason": "block requires a product with name/category/stock/specifications/brand, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard5Product[]",
+          "events": ["toggleWishlist", "addToCart", "quickView", "compare", "export"],
+          "state": "controlled",
+          "requirements": ["categoryProducts"]
+        }
+      }
+    },
+    "checkout.checkout": {
+      "default": "CheckoutForm1",
+      "variants": {
+        "CheckoutForm1": {
+          "status": "executable",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm1FormData",
+          "events": ["retryTotals", "selectShippingOption", "applyPromo", "submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        },
+        "CheckoutForm2": {
+          "status": "held",
+          "reason": "unproven checkout variant: E1 keeps only the default CheckoutForm1, whose behavior is unchanged; no verified prop bridge exists",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm2Data",
+          "events": ["submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        },
+        "CheckoutForm3": {
+          "status": "held",
+          "reason": "unproven checkout variant: E1 keeps only the default CheckoutForm1, whose behavior is unchanged; no verified prop bridge exists",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm3FormData",
+          "events": ["submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        }
+      }
+    },
+    "checkout.confirmation": {
+      "default": "CheckoutConfirmation",
+      "variants": {
+        "CheckoutConfirmation": {
+          "status": "executable",
+          "block": "CheckoutConfirmation",
+          "dataShape": "Receipt",
+          "events": ["continueShopping"],
+          "state": "uncontrolled",
+          "requirements": ["lastReceipt"]
+        }
+      }
+    },
+    "account.login": {
+      "default": "LoginPage1",
+      "variants": {
+        "LoginPage1": {
+          "status": "executable",
+          "block": "LoginPage1",
+          "dataShape": "LoginPage1FormData & AccountAuthResult",
+          "events": ["submit", "createAccount"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        },
+        "LoginPage2": {
+          "status": "held",
+          "reason": "block's onSubmit takes positional (email, password) with no remember-me field and renders a 2-column social grid; no verified prop bridge from the account element contract exists",
+          "block": "LoginPage2",
+          "dataShape": "LoginPage2Credentials & AccountAuthResult",
+          "events": ["submit", "forgotPassword", "signUp"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "account.register": {
+      "default": "SignUpPage1",
+      "variants": {
+        "SignUpPage1": {
+          "status": "executable",
+          "block": "SignUpPage1",
+          "dataShape": "SignUpPage1Data & AccountAuthResult",
+          "events": ["submit", "signIn"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "account.orders": {
+      "default": "OrderHistory2",
+      "variants": {
+        "OrderHistory2": {
+          "status": "executable",
+          "block": "OrderHistory2",
+          "dataShape": "AccountOrderView[] & OrderHistory2Labels",
+          "events": ["viewDetails"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        },
+        "OrderHistory1": {
+          "status": "held",
+          "reason": "block models one row per order item (an item-row list), the wrong shape for an order-level history; the canonical order list cannot feed it without inventing an aggregate row",
+          "block": "OrderHistory1",
+          "dataShape": "OrderHistory1Order[]",
+          "events": [],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    }
+  },
+  "capabilities": {
+    "category.search.apply": {
+      "requirements": ["adapter.getCatalogProducts(query).text"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    },
+    "category.filter.apply": {
+      "requirements": ["adapter.getProducts(query)"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    },
+    "category.price.range": {
+      "requirements": ["adapter.getAvailableFilters(query).priceRange"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    }
+  }
+}

package/recipes/catalog.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Semantic executable catalog: the single contract that states, per view slot
+// and candidate block variant, whether the variant is `executable` or `held`,
+// the block it renders, the canonical data shape it consumes, the events it
+// emits, its controlled/uncontrolled state, its requirements, and an optional
+// prop bridge from the canonical shape to the block props.
+//
+// The published shape lives in `recipes/catalog.schema.json`; this module loads
+// that same artifact and adds only the invariants the supported schema subset
+// cannot express (a held entry must carry a reason; a slot's default must be a
+// declared variant; an unverified capability must name its owning change). It
+// does not classify the initial set, derive `supported`, or wire any
+// generator/introspection — those are owned by later tasks.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateAgainstSchema, validateSchemaSupported } from '../scripts/schema-validate.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// Layout-agnostic catalog location: at the package root the catalog lives beside
+// this module (`recipes/`); in an installed skill it is distributed under
+// `skills/sf-view-gen/assets/recipes/` and addressed by relative path. Either
+// layout holds the same synced artifact, so there is one catalog source. The
+// `../scripts/schema-validate.mjs` import resolves to the package `scripts/` at
+// the root and to the skill's own `scripts/` once distributed (same directory).
+const catalogDir = existsSync(join(here, 'catalog.json'))
+  ? here
+  : join(here, '..', 'assets', 'recipes')
+
+export const CATALOG_VERSION = 1
+export const CATALOG_SCHEMA_ID = 'https://thorcommerce.dev/storefront/catalog.schema.json'
+
+const catalogSchema = JSON.parse(readFileSync(join(catalogDir, 'catalog.schema.json'), 'utf8'))
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+export function loadCatalogSchema() {
+  return catalogSchema
+}
+
+/**
+ * Load the published semantic catalog document (`recipes/catalog.json`) — the
+ * single source of the executable/held classification. Callers validate it with
+ * `validateCatalog`; classification is data, not logic (E1 task 1.2).
+ */
+export function loadCatalog() {
+  return JSON.parse(readFileSync(join(catalogDir, 'catalog.json'), 'utf8'))
+}
+
+/**
+ * The slot variant entry schema, read from the published catalog schema so the
+ * per-entry contract has exactly one source. Throws loudly if the schema is
+ * reshaped, rather than silently validating against nothing.
+ */
+function variantEntrySchema() {
+  const entry =
+    catalogSchema?.properties?.slots?.additionalProperties?.properties?.variants
+      ?.additionalProperties
+  if (!isPlainObject(entry)) {
+    throw new Error('catalog.schema.json does not declare a slot variant entry schema.')
+  }
+  return entry
+}
+
+/**
+ * Validate one slot variant entry against the published contract.
+ * Returns { ok, errors }.
+ */
+export function validateCatalogEntry(entry) {
+  const errors = validateAgainstSchema(entry, variantEntrySchema(), 'catalog entry')
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * Validate a complete catalog document against the published contract plus the
+ * invariants the schema subset cannot express. Returns { ok, errors }.
+ */
+export function validateCatalog(catalog) {
+  if (!isPlainObject(catalog)) {
+    return { ok: false, errors: ['Catalog must be a JSON object.'] }
+  }
+  const errors = validateSchemaSupported(catalogSchema)
+  errors.push(...validateAgainstSchema(catalog, catalogSchema, 'catalog'))
+
+  const slots = isPlainObject(catalog.slots) ? catalog.slots : {}
+  for (const [slotId, slot] of Object.entries(slots)) {
+    if (!isPlainObject(slot)) continue
+    const variants = isPlainObject(slot.variants) ? slot.variants : {}
+    if (Object.keys(variants).length === 0) {
+      errors.push(`Slot "${slotId}" must declare at least one variant.`)
+    }
+    if (typeof slot.default === 'string' && !hasOwn(variants, slot.default)) {
+      errors.push(`Slot "${slotId}" default "${slot.default}" is not a declared variant.`)
+    }
+    for (const [variantName, entry] of Object.entries(variants)) {
+      if (!isPlainObject(entry)) continue
+      if (entry.status === 'held' && !(typeof entry.reason === 'string' && entry.reason.length > 0)) {
+        errors.push(`Held variant "${slotId}.${variantName}" must declare a non-empty reason.`)
+      }
+    }
+  }
+
+  // An unverified capability is held: it must name the change that owns its
+  // implementation, so a consumer can see that the capability is not available
+  // and who will make it available. This is the honest gate the schema subset
+  // cannot express (E1 task 4.2 / CU-04).
+  const capabilities = isPlainObject(catalog.capabilities) ? catalog.capabilities : {}
+  for (const [capabilityId, capability] of Object.entries(capabilities)) {
+    if (!isPlainObject(capability)) continue
+    if (
+      capability.verification === 'unverified' &&
+      !(typeof capability.owner === 'string' && capability.owner.length > 0)
+    ) {
+      errors.push(
+        `Unverified capability "${capabilityId}" must declare the owning change in "owner".`
+      )
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}

package/recipes/catalog.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/catalog.schema.json",
+  "title": "Thor Commerce Storefront Semantic Catalog",
+  "description": "The semantic executable catalog: per view slot and candidate variant, its execution status (executable | held), the block it renders, its canonical data shape, emitted events, controlled/uncontrolled state, requirements, and an optional prop bridge. Held entries carry a reason. Also declares operational capabilities with their backend/data requirements and a verification state (verified | unverified); an unverified capability names its owning change in `owner`. Versioned by catalogVersion.",
+  "type": "object",
+  "required": ["catalogVersion", "slots"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "catalogVersion": { "type": "number", "enum": [1] },
+    "description": { "type": "string" },
+    "slots": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["default", "variants"],
+        "additionalProperties": false,
+        "properties": {
+          "default": { "type": "string", "minLength": 1 },
+          "variants": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["status", "block", "dataShape", "events", "state", "requirements"],
+              "additionalProperties": false,
+              "properties": {
+                "status": { "type": "string", "enum": ["executable", "held"] },
+                "reason": { "type": "string", "minLength": 1 },
+                "block": { "type": "string", "minLength": 1 },
+                "dataShape": { "type": "string", "minLength": 1 },
+                "events": { "type": "array", "items": { "type": "string" } },
+                "state": { "type": "string", "enum": ["controlled", "uncontrolled"] },
+                "requirements": { "type": "array", "items": { "type": "string" } },
+                "bridge": {
+                  "type": "object",
+                  "required": ["from", "to"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": { "type": "string", "minLength": 1 },
+                    "to": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["requirements", "verification"],
+        "additionalProperties": false,
+        "properties": {
+          "requirements": { "type": "array", "items": { "type": "string" } },
+          "verification": { "type": "string", "enum": ["verified", "unverified"] },
+          "owner": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/recipes/feature.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/feature.schema.json",
+  "title": "Storefront feature registry",
+  "type": "object",
+  "required": ["version", "features"],
+  "properties": {
+    "version": { "type": "string" },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "views", "state", "handlers", "adapter", "surfaces", "config"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "mvp": { "type": "boolean" },
+          "route": { "type": "string", "minLength": 1 },
+          "views": { "type": "array", "items": { "type": "string" } },
+          "state": { "type": "array", "items": { "type": "string" } },
+          "handlers": { "type": "array", "items": { "type": "string" } },
+          "adapter": {
+            "type": "object",
+            "required": ["needs"],
+            "properties": {
+              "needs": { "type": "array", "items": { "type": "string" } },
+              "fallback": { "type": "string" }
+            }
+          },
+          "config": {
+            "type": "object",
+            "description": "Per-feature configuration contract: a JSON Schema (the dependency-free subset) that the manifest's features[].config is validated against and whose `default` annotations seed absent fields."
+          },
+          "configRejection": {
+            "type": "object",
+            "description": "Stable diagnostic for configuration the feature does not accept. With no `when`, any non-empty config key is rejected with this code/message while an empty object stays the no-op (E1 task 3.5, e.g. checkout E_UNPROVEN_CHECKOUT_OPTION). With `when: { field, equals }`, only a config where that field equals the value is rejected (E2 task 4.12); an optional `capability` makes the rejection apply only while that catalog capability is not `verified`, so an unproven option fails loudly instead of being silently coerced to its default.",
+            "required": ["code", "message"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1 },
+              "message": { "type": "string", "minLength": 1 },
+              "when": {
+                "type": "object",
+                "required": ["field", "equals"],
+                "additionalProperties": false,
+                "properties": {
+                  "field": { "type": "string", "minLength": 1 },
+                  "equals": {}
+                }
+              },
+              "capability": { "type": "string", "minLength": 1 }
+            }
+          },
+          "presentations": {
+            "type": "object",
+            "description": "Generation-owned block wiring: maps a config value (e.g. config.presentation) to the block variant the feature mount renders.",
+            "additionalProperties": { "type": "string" }
+          },
+          "mounts": {
+            "type": "array",
+            "description": "Feature-instance mounts into a host view's slot. The engine owns the block wiring; a mount never carries an element.",
+            "items": {
+              "type": "object",
+              "required": ["id", "host", "slot"],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "host": { "type": "string", "minLength": 1 },
+                "slot": { "type": "string", "minLength": 1 }
+              }
+            }
+          },
+          "surfaces": {
+            "type": "array",
+            "description": "Legacy additive alias for existing held registry entries; derived from mounts where both exist.",
+            "items": {
+              "type": "object",
+              "required": ["host", "slot", "element"],
+              "properties": {
+                "host": { "type": "string" },
+                "slot": { "type": "string" },
+                "element": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}