@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/recipes/validate.mjs

@@ -1,13 +1,41 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { loadCatalog } from './catalog.mjs'
+import { validateAgainstSchema } from '../scripts/schema-validate.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
 
-const recipes = JSON.parse(readFileSync(join(here, 'recipes.json'), 'utf8'))
-const sections = JSON.parse(readFileSync(join(here, 'sections.json'), 'utf8'))
-const archetypes = JSON.parse(readFileSync(join(here, 'archetypes.json'), 'utf8'))
+// Layout-agnostic registry location: at the package root the JSON registry lives
+// beside this module (`recipes/`); in an installed skill it is distributed under
+// `skills/sf-view-gen/assets/recipes/` and addressed by relative path. Both hold
+// the same synced copies, so the registry has one source.
+const registryDir = existsSync(join(here, 'recipes.json'))
+  ? here
+  : join(here, '..', 'assets', 'recipes')
+
+const recipes = JSON.parse(readFileSync(join(registryDir, 'recipes.json'), 'utf8'))
+const sections = JSON.parse(readFileSync(join(registryDir, 'sections.json'), 'utf8'))
+const archetypes = JSON.parse(readFileSync(join(registryDir, 'archetypes.json'), 'utf8'))
+const features = JSON.parse(readFileSync(join(registryDir, 'features.json'), 'utf8'))
+
+// The semantic catalog is the single source of the executable/held
+// classification. `supported` (what the CLI presents as selectable) is derived
+// from `status === 'executable'`; held variants are never selectable. The
+// catalog is loaded once, read-only.
+const catalog = loadCatalog()
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+// Own-property lookup: inherited keys (`constructor`, `__proto__`, `toString`)
+// must never be treated as a declared slot/intent, or an unsupported input
+// would resolve to an inherited member and throw instead of being reported.
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
 
 export function loadRecipes() {
   return recipes
@@ -17,11 +45,279 @@ export function loadArchetypes() {
   return archetypes
 }
 
+export function loadFeatures() {
+  return features
+}
+
+export function getFeature(name) {
+  return features.features.find((f) => f.name === name) ?? null
+}
+
+export function allowedFeatureNames() {
+  return features.features.map((f) => f.name)
+}
+
+export function isAllowedFeature(name) {
+  return allowedFeatureNames().includes(name)
+}
+
+/**
+ * The per-feature configuration contract declared by the registry, or null when
+ * the feature is unknown or declares none. The contract is a JSON Schema in the
+ * dependency-free subset (`scripts/schema-validate.mjs`); its `default`
+ * annotations seed absent config fields.
+ */
+export function featureConfigContract(featureName) {
+  const contract = getFeature(featureName)?.config
+  return isPlainObject(contract) ? contract : null
+}
+
+/**
+ * The stable diagnostic a feature declares for configuration it does not accept
+ * (E1 task 3.5). `checkout` declares `E_UNPROVEN_CHECKOUT_OPTION`: E1 has proven
+ * no checkout variant or route option, so any non-empty key is rejected with the
+ * code while an empty `{}` stays the existing no-op. Returns null when the
+ * feature declares none, so its config contract alone governs.
+ */
+export function featureConfigRejection(featureName) {
+  const rejection = getFeature(featureName)?.configRejection
+  if (!isPlainObject(rejection) || typeof rejection.code !== 'string') return null
+  return rejection
+}
+
+// A capability is verified only when the catalog explicitly says so; a missing
+// entry or any other state is unverified. Presence of a method is not proof.
+function isCapabilityVerified(capabilityId) {
+  const capabilities = isPlainObject(catalog.capabilities) ? catalog.capabilities : {}
+  return hasOwn(capabilities, capabilityId) && capabilities[capabilityId]?.verification === 'verified'
+}
+
+/**
+ * The rejection that applies to a specific config value (E1 task 3.5 extended by
+ * E2 task 4.12). A rejection with no `when` applies to any non-empty config
+ * (checkout's existing behavior). A rejection with `when: { field, equals }`
+ * applies only when `config[field] === equals`, so a feature may accept most of
+ * its config while still refusing one unprovable option. When the rejection
+ * declares a `capability`, it applies only while that catalog capability is not
+ * `verified`: a configured-but-unproven option fails loudly until the backend
+ * proves it, and is never silently coerced to its default. Returns the rejection
+ * spec when it applies, else null.
+ */
+export function featureConfigRejectionFor(featureName, config) {
+  const rejection = featureConfigRejection(featureName)
+  if (!rejection || !isPlainObject(config)) return null
+  const when = isPlainObject(rejection.when) ? rejection.when : null
+  if (when) {
+    if (typeof when.field !== 'string' || !hasOwn(config, when.field)) return null
+    if (config[when.field] !== when.equals) return null
+  } else if (Object.keys(config).length === 0) {
+    return null
+  }
+  if (typeof rejection.capability === 'string' && isCapabilityVerified(rejection.capability)) {
+    return null
+  }
+  return rejection
+}
+
+// Stable diagnostics for feature instance mounts (E1 task 3.7 / CU-06). A mount
+// declares `{ id, host, slot }`; `id` is unique across installed features and a
+// host slot is claimed by at most one instance. These are stable strings so the
+// CLI, the plan/apply engine, and tests assert the same contract.
+export const MOUNT_CONFLICT_CODE = 'E_MOUNT_CONFLICT'
+export const DUPLICATE_MOUNT_ID_CODE = 'E_DUPLICATE_MOUNT_ID'
+
+/**
+ * Resolve the host-slot claims declared by a set of installed feature entries
+ * against the registry (E1 task 3.7 / CU-06). The registry is the single
+ * authority for which mounts a feature declares; `options.getFeatureSpec`
+ * defaults to `getFeature` and is the seam a hermetic test uses to inject a
+ * second registry claim without adding a generic registry feature.
+ *
+ * Invariants enforced here, before any write:
+ *   - every mount declares non-empty string `id`, `host`, and `slot`;
+ *   - a mount `id` is unique across installed features (`E_DUPLICATE_MOUNT_ID`);
+ *   - at most one instance claims a given `(host, slot)` (`E_MOUNT_CONFLICT`).
+ *
+ * Returns `{ ok, errors, claims }`, where `claims` maps `"<host>.<slot>"` to
+ * `{ id, host, slot, featureName }` so generation and later tasks read one
+ * resolved claim set instead of re-deriving it.
+ */
+export function resolveMountClaims(featureEntries, options = {}) {
+  const resolve =
+    typeof options.getFeatureSpec === 'function' ? options.getFeatureSpec : getFeature
+  const errors = []
+  const claims = new Map()
+  const ids = new Map()
+  const entries = Array.isArray(featureEntries) ? featureEntries : []
+  for (const entry of entries) {
+    if (!isPlainObject(entry) || typeof entry.name !== 'string') continue
+    const spec = resolve(entry.name)
+    const mounts = Array.isArray(spec?.mounts) ? spec.mounts : []
+    for (const mount of mounts) {
+      if (!isPlainObject(mount)) {
+        errors.push(
+          `Feature "${entry.name}" declares a malformed mount; expected { id, host, slot }.`,
+        )
+        continue
+      }
+      const { id, host, slot } = mount
+      if (
+        typeof id !== 'string' || id.length === 0 ||
+        typeof host !== 'string' || host.length === 0 ||
+        typeof slot !== 'string' || slot.length === 0
+      ) {
+        errors.push(
+          `Feature "${entry.name}" mount must declare non-empty "id", "host", and "slot".`,
+        )
+        continue
+      }
+      if (ids.has(id)) {
+        errors.push(
+          `${DUPLICATE_MOUNT_ID_CODE}: mount id "${id}" is declared by feature "${ids.get(id)}" and again by feature "${entry.name}"; instance ids must be unique across installed features.`,
+        )
+        continue
+      }
+      ids.set(id, entry.name)
+      const slotKey = `${host}.${slot}`
+      const existing = claims.get(slotKey)
+      if (existing) {
+        errors.push(
+          `${MOUNT_CONFLICT_CODE}: host slot "${slotKey}" is already claimed by mount "${existing.id}" of feature "${existing.featureName}"; mount "${id}" of feature "${entry.name}" cannot claim the same (host, slot).`,
+        )
+        continue
+      }
+      claims.set(slotKey, { id, host, slot, featureName: entry.name })
+    }
+  }
+  return { ok: errors.length === 0, errors, claims }
+}
+
+/**
+ * The legacy `surfaces` alias for a registry feature, derived from its declared
+ * `mounts` when it has any (E1 task 3.7). A mount carries no `element`: the
+ * element is generation-owned, read here from the feature's `presentations` map
+ * for its default presentation, so `mounts` stays the single source and
+ * `surfaces` is a read-only alias. A feature that declares no mounts (the held
+ * `recommendations` entry) keeps its existing `surfaces`.
+ */
+export function featureSurfaces(spec) {
+  if (!isPlainObject(spec)) return []
+  const mounts = Array.isArray(spec.mounts) ? spec.mounts : []
+  if (mounts.length === 0) {
+    return Array.isArray(spec.surfaces) ? spec.surfaces : []
+  }
+  const presentations = isPlainObject(spec.presentations) ? spec.presentations : {}
+  const contract = isPlainObject(spec.config) ? spec.config : {}
+  const properties = isPlainObject(contract.properties) ? contract.properties : {}
+  const field = isPlainObject(properties.presentation) ? properties.presentation : {}
+  const element =
+    typeof field.default === 'string' && typeof presentations[field.default] === 'string'
+      ? presentations[field.default]
+      : Object.values(presentations).find((value) => typeof value === 'string')
+  return mounts
+    .filter(
+      (mount) =>
+        isPlainObject(mount) &&
+        typeof mount.host === 'string' &&
+        typeof mount.slot === 'string',
+    )
+    .map((mount) => ({
+      host: mount.host,
+      slot: mount.slot,
+      ...(typeof element === 'string' ? { element } : {}),
+    }))
+}
+
+// One stable, actionable line for a rejected non-empty config: the declared
+// code and message plus the rejected key(s), so the CLI and the persisted
+// sync/doctor preflight report the same diagnostic.
+function configRejectionError(rejection, config) {
+  // A conditional rejection names only its offending field; a whole-config
+  // rejection (checkout) names every supplied key.
+  const field =
+    isPlainObject(rejection.when) && typeof rejection.when.field === 'string'
+      ? rejection.when.field
+      : null
+  const keys = field
+    ? JSON.stringify(field)
+    : Object.keys(config)
+        .map((key) => JSON.stringify(key))
+        .join(', ')
+  return `${rejection.code}: ${rejection.message}. Rejected key(s): ${keys}.`
+}
+
+/**
+ * Normalize and validate a config against a feature config contract. Declared
+ * `default` annotations seed absent fields; unknown fields are rejected when the
+ * contract sets `additionalProperties: false`. Returns `{ ok, config, errors }`.
+ *
+ * Pure over its arguments so it is fixture-testable and reusable by the later
+ * plan/apply operation engine (E1 task 3.1); the registry-backed wrapper is
+ * `normalizeFeatureConfig`.
+ */
+export function normalizeConfig(contract, config) {
+  const shape = isPlainObject(contract) ? contract : {}
+  if (!isPlainObject(config)) {
+    return { ok: false, config: {}, errors: ['config must be a JSON object.'] }
+  }
+  const errors = validateAgainstSchema(config, shape, 'config')
+  const properties = isPlainObject(shape.properties) ? shape.properties : {}
+  const normalized = { ...config }
+  for (const [key, field] of Object.entries(properties)) {
+    if (!hasOwn(normalized, key) && isPlainObject(field) && hasOwn(field, 'default')) {
+      // Clone array/object defaults so a caller mutating the returned config can
+      // never mutate the registry's loaded contract.
+      normalized[key] =
+        Array.isArray(field.default) || isPlainObject(field.default)
+          ? structuredClone(field.default)
+          : field.default
+    }
+  }
+  return { ok: errors.length === 0, config: normalized, errors }
+}
+
+/**
+ * Registry-backed config normalization: resolve the feature's declared contract
+ * and validate/default the caller's config against it. An unknown feature is an
+ * error, so a config can never be persisted for a feature the registry does not
+ * declare. Returns `{ ok, config, errors }`.
+ */
+export function normalizeFeatureConfig(featureName, config) {
+  const spec = getFeature(featureName)
+  if (!spec) {
+    return {
+      ok: false,
+      config: {},
+      errors: [
+        `Unknown feature "${featureName}". Allowed features: ${allowedFeatureNames().join(', ')}.`,
+      ],
+    }
+  }
+  const contract = isPlainObject(spec.config)
+    ? spec.config
+    : { type: 'object', additionalProperties: false, properties: {} }
+  const result = normalizeConfig(contract, config)
+  // A feature that declares no proven configuration (E1 task 3.5) rejects any
+  // non-empty config with its stable code instead of a generic schema error; the
+  // empty object remains the existing no-op. E2 task 4.12 extends this to a
+  // conditional, capability-gated rejection: only the declared offending field
+  // value is refused while its capability is unverified, and the rest of the
+  // feature's config stays valid.
+  const rejection = featureConfigRejectionFor(featureName, config)
+  const errors = rejection ? [configRejectionError(rejection, config)] : result.errors
+  return {
+    ok: errors.length === 0,
+    config: result.config,
+    errors: errors.map((error) => `Feature "${featureName}" ${error}`),
+  }
+}
+
 /**
  * Resolve a slot id ("<view>.<slot>") to its archetype definition, or null.
  */
 export function getSlotArchetype(viewName, slot) {
-  return archetypes.slots[`${viewName}.${slot}`] ?? null
+  const key = `${viewName}.${slot}`
+  return hasOwn(archetypes.slots, key) ? archetypes.slots[key] : null
 }
 
 /**
@@ -35,17 +331,21 @@ export function resolveIntent(viewName, slot, intentName) {
     errors.push(`Slot "${slot}" has no archetype for view "${viewName}".`)
     return { ok: false, errors }
   }
-  const intent = slotArchetype.intents[intentName]
-  if (!intent) {
+  const intents = isPlainObject(slotArchetype.intents) ? slotArchetype.intents : {}
+  if (!hasOwn(intents, intentName)) {
     errors.push(
-      `Unknown intent "${intentName}" for slot "${slot}" in view "${viewName}". Allowed intents: ${Object.keys(slotArchetype.intents).join(', ')}.`
+      `Unknown intent "${intentName}" for slot "${slot}" in view "${viewName}". Allowed intents: ${Object.keys(intents).join(', ')}.`
     )
     return { ok: false, errors }
   }
-  if (!isAllowedVariant(viewName, slot, intent.variant)) {
-    const allowed = getRecipe(viewName)?.allowedVariants[slot] ?? []
+  const intent = intents[intentName]
+  if (!isAllowedVariant(viewName, slot, intent?.variant)) {
+    const allowedBySlot = isPlainObject(getRecipe(viewName)?.allowedVariants)
+      ? getRecipe(viewName).allowedVariants
+      : {}
+    const allowed = hasOwn(allowedBySlot, slot) && Array.isArray(allowedBySlot[slot]) ? allowedBySlot[slot] : []
     errors.push(
-      `Intent "${intentName}" resolves to variant "${intent.variant}", which is not allowed for slot "${slot}" in view "${viewName}". Allowed variants: ${allowed.join(', ') || '(none)'}.`
+      `Intent "${intentName}" resolves to variant "${intent?.variant}", which is not allowed for slot "${slot}" in view "${viewName}". Allowed variants: ${allowed.join(', ') || '(none)'}.`
     )
     return { ok: false, errors }
   }
@@ -56,6 +356,126 @@ export function loadSections() {
   return sections
 }
 
+// The editorial section registry declares each entry's `status` — `executable`
+// (shipped) or `held` (bounded curation). This mirrors the semantic catalog's
+// `status`/`reason` convention (`recipes/catalog.json`): a held entry MUST carry
+// a non-empty `reason`; there is no separate held list, so the registry stays the
+// single source of truth the validation and the CLI introspection read.
+export const SECTION_STATUSES = ['executable', 'held']
+
+/**
+ * The invariant errors in the section registry the JSON schema subset cannot
+ * express: every entry declares a known `status`; a `held` entry names its
+ * bounded reason; an `executable` entry declares its element type, variants, and
+ * a default variant drawn from those variants. Returns a list of messages (empty
+ * when the registry is well-formed).
+ */
+export function sectionStatusErrors() {
+  const errors = []
+  const list = Array.isArray(sections.sections) ? sections.sections : []
+  for (const section of list) {
+    if (!isPlainObject(section) || typeof section.name !== 'string' || section.name.length === 0) {
+      errors.push('A section registry entry must declare a non-empty "name".')
+      continue
+    }
+    const { name } = section
+    if (!SECTION_STATUSES.includes(section.status)) {
+      errors.push(
+        `Section "${name}" must declare a status of ${SECTION_STATUSES.join(' | ')}.`
+      )
+      continue
+    }
+    if (section.status === 'held' && !(typeof section.reason === 'string' && section.reason.length > 0)) {
+      errors.push(`Held section "${name}" must declare a non-empty reason.`)
+    }
+    if (section.status === 'executable') {
+      if (!(typeof section.elementType === 'string' && section.elementType.length > 0)) {
+        errors.push(`Executable section "${name}" must declare an "elementType".`)
+      }
+      const variants = Array.isArray(section.variants) ? section.variants : []
+      if (variants.length === 0) {
+        errors.push(`Executable section "${name}" must declare at least one variant.`)
+      } else if (!variants.includes(section.defaultVariant)) {
+        errors.push(
+          `Executable section "${name}" default "${section.defaultVariant}" is not a declared variant.`
+        )
+      }
+    }
+  }
+  return errors
+}
+
+/** The registry entries whose status is `executable`, in registry order. */
+export function availableSections() {
+  const list = Array.isArray(sections.sections) ? sections.sections : []
+  return list.filter((section) => section.status === 'executable')
+}
+
+/** The names of the executable section types, in registry order. */
+export function availableSectionNames() {
+  return availableSections().map((section) => section.name)
+}
+
+/** The registry entries whose status is `held`, in registry order. */
+export function heldSections() {
+  const list = Array.isArray(sections.sections) ? sections.sections : []
+  return list.filter((section) => section.status === 'held')
+}
+
+/** The names of the held section types, in registry order. */
+export function heldSectionNames() {
+  return heldSections().map((section) => section.name)
+}
+
+/** The declared status of a section type, or null when it is not registered. */
+export function sectionStatus(name) {
+  const section = sections.sections.find((entry) => entry.name === name)
+  return section ? section.status : null
+}
+
+/** The bounded-curation reason of a held section type, or null otherwise. */
+export function heldSectionReason(name) {
+  const section = sections.sections.find((entry) => entry.name === name)
+  return section?.status === 'held' && typeof section.reason === 'string' ? section.reason : null
+}
+
+/**
+ * The section registry projected for introspection: each type with its status
+ * and, for a held type, its bounded reason. Held types are visibly held rather
+ * than presented as available.
+ */
+export function sectionRegistry() {
+  const list = Array.isArray(sections.sections) ? sections.sections : []
+  return list.map((section) => ({
+    name: section.name,
+    status: section.status,
+    ...(section.status === 'held' && typeof section.reason === 'string'
+      ? { reason: section.reason }
+      : {}),
+  }))
+}
+
+/**
+ * The full registry entry for a section type, or null when it is not
+ * registered. Unlike `sectionRegistry()` (the projected introspection view),
+ * this exposes every declared field — including `dataBound` and `variants` —
+ * so the CLI can tell which instances need user-owned source configuration.
+ */
+export function sectionDefinitionByName(name) {
+  const list = Array.isArray(sections.sections) ? sections.sections : []
+  return list.find((entry) => isPlainObject(entry) && entry.name === name) ?? null
+}
+
+/**
+ * Whether a section type resolves its content from a data source configured by
+ * the user (for example the `products` type) rather than from static editorial
+ * content. Unregistered types are not data-bound.
+ */
+export function sectionIsDataBound(name) {
+  const section = sectionDefinitionByName(name)
+  return section?.status === 'executable' && section.dataBound === true
+}
+
 export function getRecipe(name) {
   return recipes.views.find((v) => v.name === name) ?? null
 }
@@ -64,18 +484,192 @@ export function allowedViewNames() {
   return recipes.views.map((v) => v.name)
 }
 
+/**
+ * The curated MVP unit set. Only these units are shipped and buildable today;
+ * everything else is a traced post-MVP backlog item. The set is declared on the
+ * registry entries themselves (`mvp: true`) so introspection and validation read
+ * one source of truth.
+ */
+export function curatedViewNames() {
+  return recipes.views.filter((v) => v.mvp === true).map((v) => v.name)
+}
+
+export function isCuratedView(name) {
+  return getRecipe(name)?.mvp === true
+}
+
+export function curatedFeatureNames() {
+  return features.features.filter((f) => f.mvp === true).map((f) => f.name)
+}
+
+export function isCuratedFeature(name) {
+  return getFeature(name)?.mvp === true
+}
+
+/**
+ * The starter composition: every curated (installable) feature plus every
+ * curated view no installed curated feature owns. A feature-owned view (for
+ * example `checkout`, owned by the `checkout` feature) is installed through its
+ * feature, not listed directly. The set is derived from the registry's
+ * `mvp: true` declaration — never a hand-maintained list — so a curated unit
+ * added or removed flows automatically and a held unit (`recommendations`, a
+ * held section) is excluded by construction.
+ *
+ * `registries` is the injection seam for tests: pass fixture `{ views }` /
+ * `{ features }` sources to exercise the derivation without mutating the loaded
+ * registry.
+ */
+export function starterComposition(registries = {}) {
+  const recipeSource = registries.recipes ?? recipes
+  const featureSource = registries.features ?? features
+  const featureNames = featureSource.features
+    .filter((f) => f.mvp === true)
+    .map((f) => f.name)
+  const ownedViews = new Set()
+  for (const name of featureNames) {
+    const feature = featureSource.features.find((f) => f.name === name)
+    for (const view of Array.isArray(feature?.views) ? feature.views : []) {
+      ownedViews.add(view)
+    }
+  }
+  const viewNames = recipeSource.views
+    .filter((v) => v.mvp === true)
+    .map((v) => v.name)
+    .filter((name) => !ownedViews.has(name))
+  return { views: viewNames, features: featureNames }
+}
+
+/**
+ * The catalog entry for one slot ("<view>.<slot>"), or null when the slot is
+ * outside the catalog scope (a held, non-curated view). The catalog is the
+ * single classification source; nothing here hardcodes a variant.
+ */
+export function getCatalogSlot(viewName, slot) {
+  const slots = isPlainObject(catalog.slots) ? catalog.slots : {}
+  const key = `${viewName}.${slot}`
+  return hasOwn(slots, key) ? slots[key] : null
+}
+
+/**
+ * The catalog entry for one variant of a slot, or null when the slot or the
+ * variant is outside the catalog scope. Used to name a held variant's reason at
+ * the point a selection is rejected (E1 task 1.4 / CU-07).
+ */
+export function getCatalogVariant(viewName, slot, variant) {
+  const slotEntry = getCatalogSlot(viewName, slot)
+  const variants = isPlainObject(slotEntry?.variants) ? slotEntry.variants : {}
+  return hasOwn(variants, variant) ? variants[variant] : null
+}
+
+/**
+ * The variant names the catalog classifies as `executable` for a slot — the
+ * only selectable set. Held variants are excluded by construction.
+ */
+export function executableVariants(viewName, slot) {
+  const slotEntry = getCatalogSlot(viewName, slot)
+  const variants = isPlainObject(slotEntry?.variants) ? slotEntry.variants : {}
+  return Object.entries(variants)
+    .filter(([, entry]) => isPlainObject(entry) && entry.status === 'executable')
+    .map(([variantName]) => variantName)
+}
+
+/**
+ * The catalog slice for a view: every declared slot ("<view>.<slot>") with its
+ * variants and their executable/held status. Introspection reports this so a
+ * held variant is visible with its reason and never presented as selectable.
+ */
+export function viewCatalog(viewName) {
+  const slots = isPlainObject(catalog.slots) ? catalog.slots : {}
+  const out = {}
+  for (const [slotId, slot] of Object.entries(slots)) {
+    if (slotId.startsWith(`${viewName}.`)) out[slotId] = slot
+  }
+  return out
+}
+
+function slotNameFromId(viewName, slotId) {
+  return slotId.slice(viewName.length + 1)
+}
+
+/**
+ * Selectable variants per slot, derived from the catalog executable set.
+ * Returns { slot: [variant, ...] }. Slots outside the catalog are omitted, so
+ * a held view never advertises a selectable variant.
+ */
+export function allowedVariantsForView(viewName) {
+  const out = {}
+  for (const slotId of Object.keys(viewCatalog(viewName))) {
+    const slot = slotNameFromId(viewName, slotId)
+    out[slot] = executableVariants(viewName, slot)
+  }
+  return out
+}
+
+/**
+ * The supported (executable) default variant per slot, derived from the
+ * catalog. Legacy single-value alias of the executable set. Returns
+ * { slot: variant }.
+ */
+export function supportedVariantsForView(viewName) {
+  const out = {}
+  for (const [slotId, slot] of Object.entries(viewCatalog(viewName))) {
+    if (typeof slot.default === 'string') {
+      out[slotNameFromId(viewName, slotId)] = slot.default
+    }
+  }
+  return out
+}
+
+/**
+ * The supported default variant for a slot (legacy single-value accessor). The
+ * default is executable by contract; null when the slot is outside the catalog.
+ */
+export function supportedVariant(viewName, slot) {
+  const slotEntry = getCatalogSlot(viewName, slot)
+  return typeof slotEntry?.default === 'string' ? slotEntry.default : null
+}
+
+export function isSupportedVariant(viewName, slot, variant) {
+  return executableVariants(viewName, slot).includes(variant)
+}
+
+/**
+ * Supported intent names per slot: intents whose resolved variant is
+ * executable. Returns { slot: [intent, ...] }.
+ */
+export function supportedIntents(viewName) {
+  const out = {}
+  for (const slotId of Object.keys(viewCatalog(viewName))) {
+    const slot = slotNameFromId(viewName, slotId)
+    const slotArchetype = getSlotArchetype(viewName, slot)
+    const intents = isPlainObject(slotArchetype?.intents) ? slotArchetype.intents : {}
+    const executable = new Set(executableVariants(viewName, slot))
+    out[slot] = Object.entries(intents)
+      .filter(([, intent]) => executable.has(intent?.variant))
+      .map(([intentName]) => intentName)
+  }
+  return out
+}
+
+export function isSupportedIntent(viewName, slot, intentName) {
+  const supported = supportedIntents(viewName)
+  return Array.isArray(supported[slot]) && supported[slot].includes(intentName)
+}
+
 export function isAllowedVariant(viewName, slot, variant) {
   const recipe = getRecipe(viewName)
   if (!recipe) return false
-  const allowed = recipe.allowedVariants[slot]
-  if (!allowed) return false
-  return allowed.includes(variant)
+  const allowedBySlot = isPlainObject(recipe.allowedVariants) ? recipe.allowedVariants : {}
+  if (!hasOwn(allowedBySlot, slot)) return false
+  const allowed = allowedBySlot[slot]
+  return Array.isArray(allowed) && allowed.includes(variant)
 }
 
 export function isAllowedSection(viewName, sectionName) {
   const recipe = getRecipe(viewName)
   if (!recipe) return false
-  if (!recipe.optionalSections.includes(sectionName)) return false
+  const optionalSections = Array.isArray(recipe.optionalSections) ? recipe.optionalSections : []
+  if (!optionalSections.includes(sectionName)) return false
   return sections.sections.some((s) => s.name === sectionName)
 }
 
@@ -86,40 +680,242 @@ export function isAllowedSection(viewName, sectionName) {
  */
 export function validateComposition(composition) {
   const errors = []
-  const recipe = getRecipe(composition.view)
+  const viewName = isPlainObject(composition) ? composition.view : undefined
+  const recipe = getRecipe(viewName)
   if (!recipe) {
+    errors.push(`Unknown view "${viewName}". Allowed views: ${allowedViewNames().join(', ')}.`)
+    return { ok: false, errors }
+  }
+  if (!isCuratedView(viewName)) {
     errors.push(
-      `Unknown view "${composition.view}". Allowed views: ${allowedViewNames().join(', ')}.`
+      `View "${viewName}" is outside the curated MVP set (${curatedViewNames().join(', ')}). It is held post-MVP.`
     )
     return { ok: false, errors }
   }
 
-  for (const [slot, intentName] of Object.entries(composition.intents ?? {})) {
-    const resolved = resolveIntent(composition.view, slot, intentName)
-    if (!resolved.ok) errors.push(...resolved.errors)
+  const intents = isPlainObject(composition.intents) ? composition.intents : {}
+  for (const [slot, intentName] of Object.entries(intents)) {
+    const resolved = resolveIntent(viewName, slot, intentName)
+    if (!resolved.ok) {
+      errors.push(...resolved.errors)
+      continue
+    }
+    if (!isSupportedIntent(viewName, slot, intentName)) {
+      const supported = supportedIntents(viewName)[slot] ?? []
+      errors.push(
+        `Intent "${intentName}" is not supported by the curated MVP set for slot "${slot}" in view "${viewName}". Supported intents: ${supported.join(', ') || '(none)'}.`
+      )
+    }
+  }
+
+  const variants = isPlainObject(composition.variants) ? composition.variants : {}
+  const allowedBySlot = isPlainObject(recipe.allowedVariants) ? recipe.allowedVariants : {}
+  for (const [slot, variant] of Object.entries(variants)) {
+    if (!hasOwn(allowedBySlot, slot)) {
+      errors.push(
+        `Slot "${slot}" has no variants for view "${viewName}". Allowed slots: ${Object.keys(allowedBySlot).join(', ') || '(none)'}.`
+      )
+      continue
+    }
+    if (!isAllowedVariant(viewName, slot, variant)) {
+      const allowed = Array.isArray(allowedBySlot[slot]) ? allowedBySlot[slot] : []
+      errors.push(
+        `Variant "${variant}" is not allowed for slot "${slot}" in view "${viewName}". Allowed: ${allowed.join(', ') || '(none)'}.`
+      )
+      continue
+    }
+    if (!isSupportedVariant(viewName, slot, variant)) {
+      const supported = executableVariants(viewName, slot)
+      // A held variant is rejected with its catalog reason so the diagnostic is
+      // actionable; an allowed-but-unknown variant keeps the legacy wording.
+      const heldEntry = getCatalogVariant(viewName, slot, variant)
+      const heldDetail =
+        heldEntry?.status === 'held' && typeof heldEntry.reason === 'string'
+          ? ` Held reason: ${heldEntry.reason}.`
+          : ''
+      errors.push(
+        `Variant "${variant}" is not supported by the curated MVP set for slot "${slot}" in view "${viewName}".${heldDetail} Supported variants: ${supported.join(', ') || '(none)'}.`
+      )
+    }
+  }
+
+  // A slot selected by both an intent and a variant has two competing truths;
+  // reject it before any write (E1 task 2.2 / the `view.add` operation contract).
+  for (const slot of Object.keys(intents)) {
+    if (hasOwn(variants, slot)) {
+      errors.push(
+        `Slot "${slot}" in view "${viewName}" is selected by both an intent and a variant; choose exactly one.`
+      )
+    }
   }
 
-  for (const [slot, variant] of Object.entries(composition.variants ?? {})) {
-    if (!isAllowedVariant(composition.view, slot, variant)) {
-      const allowed = recipe.allowedVariants[slot] ?? []
+  // The ordered per-view composition (E3): a new-form entry is
+  // `{ id, type, variant? }` — a registered-slot entry uses the reserved
+  // `id === "slot:" + type` form and an editorial instance a persisted id that
+  // does not start with `slot:`. The legacy `{ name, variant }` shape stays
+  // accepted until the deterministic migration rewrites it, and is still held
+  // post-MVP. The cross-entry invariants the published schema cannot express
+  // (reserved form, registered slot, allowed type, duplicate id, the editorial
+  // `maxSections` bound) are enforced here so a hand-edited manifest is refused
+  // before any write.
+  const sectionsList = Array.isArray(composition.sections) ? composition.sections : []
+  const optionalSections = Array.isArray(recipe.optionalSections) ? recipe.optionalSections : []
+  const allowedSections = Array.isArray(recipe.allowedSections) ? recipe.allowedSections : []
+  const registeredSlots = Array.isArray(recipe.registeredSlots) ? recipe.registeredSlots : []
+  const maxSections = typeof recipe.maxSections === 'number' ? recipe.maxSections : null
+  const seenSectionIds = new Set()
+  let editorialCount = 0
+  for (const section of sectionsList) {
+    if (!isPlainObject(section)) {
+      errors.push(`A section entry in view "${viewName}" must be an object.`)
+      continue
+    }
+    const hasId = typeof section.id === 'string' && section.id.length > 0
+    const hasType = typeof section.type === 'string' && section.type.length > 0
+    if (hasId || hasType) {
+      if (!hasId || !hasType) {
+        errors.push(
+          `A section entry in view "${viewName}" must declare both "id" and "type" (or a legacy "name").`
+        )
+        continue
+      }
+      if (section.id.startsWith('slot:')) {
+        if (section.id !== `slot:${section.type}`) {
+          errors.push(
+            `Reserved slot id "${section.id}" in view "${viewName}" must equal "slot:${section.type}".`
+          )
+        } else if (!registeredSlots.includes(section.type)) {
+          errors.push(
+            `Slot "${section.type}" is not a registered slot of view "${viewName}".`
+          )
+        }
+      } else {
+        editorialCount += 1
+        if (!allowedSections.includes(section.type)) {
+          errors.push(
+            `Section "${section.type}" is not an allowed section for view "${viewName}". Allowed: ${allowedSections.join(', ') || '(none)'}.`
+          )
+        }
+      }
+      if (seenSectionIds.has(section.id)) {
+        errors.push(`Duplicate section id "${section.id}" in view "${viewName}".`)
+      } else {
+        seenSectionIds.add(section.id)
+      }
+      continue
+    }
+
+    const sectionName = section.name
+    if (!isAllowedSection(viewName, sectionName)) {
       errors.push(
-        `Variant "${variant}" is not allowed for slot "${slot}" in view "${composition.view}". Allowed: ${allowed.join(', ') || '(none)'}.`
+        `Section "${sectionName}" is not allowed in view "${viewName}". Allowed: ${optionalSections.join(', ') || '(none)'}.`
       )
+      continue
     }
+    errors.push(
+      `Section "${sectionName}" is not supported by the curated MVP set for view "${viewName}". Sections are held post-MVP.`
+    )
+  }
+  if (maxSections !== null && editorialCount > maxSections) {
+    errors.push(
+      `View "${viewName}" declares ${editorialCount} editorial sections, exceeding maxSections ${maxSections}.`
+    )
   }
 
-  for (const section of composition.sections ?? []) {
-    if (!isAllowedSection(composition.view, section.name)) {
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * Validate a complete composition manifest against the registry.
+ *
+ * Every installed view must be a known recipe whose intents, variants, and
+ * sections resolve; every installed feature must be a known registry feature;
+ * and feature/view dependencies must be consistent:
+ *   - a view owned by a feature cannot be installed on its own (it must arrive
+ *     through `storefront feature add <feature>`), and
+ *   - an installed feature must have all of its owned views installed.
+ *
+ * Returns { ok, errors }.
+ */
+export function validateCompositionManifest(manifest, options = {}) {
+  const errors = []
+  const views = Array.isArray(manifest?.views) ? manifest.views : []
+  const featureList = Array.isArray(manifest?.features) ? manifest.features : []
+
+  for (const view of views) {
+    if (!isPlainObject(view) || typeof view.name !== 'string') continue
+    const result = validateComposition({
+      view: view.name,
+      intents: view.intents ?? {},
+      variants: view.variants ?? {},
+      sections: view.sections ?? [],
+    })
+    if (!result.ok) errors.push(...result.errors)
+  }
+
+  const installedFeatures = new Set()
+  for (const feature of featureList) {
+    if (!isPlainObject(feature) || typeof feature.name !== 'string') continue
+    if (!isAllowedFeature(feature.name)) {
+      errors.push(
+        `Unknown feature "${feature.name}". Allowed features: ${allowedFeatureNames().join(', ')}.`
+      )
+      continue
+    }
+    // Validate the persisted config against the feature's declared contract
+    // before any write, independent of the feature's executable/held status
+    // (E1 task 3.2 / CU-06): a manually edited or untrusted manifest must never
+    // reach generation with a config that violates the contract. A held feature
+    // still reports its held gate below, so a valid config never unholds it, and
+    // an invalid config is named by field even when the feature is held. A
+    // feature that accepts no configuration (E1 task 3.5) reports its stable
+    // rejection code here too, so `sync`/`doctor` reject a persisted non-empty
+    // checkout config before writing.
+    const configResult = normalizeFeatureConfig(
+      feature.name,
+      hasOwn(feature, 'config') ? feature.config : {}
+    )
+    if (!configResult.ok) {
+      errors.push(...configResult.errors)
+    }
+    if (!isCuratedFeature(feature.name)) {
       errors.push(
-        `Section "${section.name}" is not allowed in view "${composition.view}". Allowed: ${recipe.optionalSections.join(', ') || '(none)'}.`
+        `Feature "${feature.name}" is outside the curated MVP set (${curatedFeatureNames().join(', ')}). It is held post-MVP.`
       )
       continue
     }
-    if (section.variant) {
-      const def = sections.sections.find((s) => s.name === section.name)
-      if (def && !def.variants.includes(section.variant)) {
+    installedFeatures.add(feature.name)
+  }
+
+  // Host-slot claim rules (E1 task 3.7 / CU-06): a mount id is unique across
+  // installed features and a `(host, slot)` is claimed by at most one instance.
+  // Resolved through the same registry authority (`options.getFeatureSpec` is
+  // the injection seam), so `sync`/`doctor`/`feature add` reject a conflicting
+  // claim before any write.
+  const claims = resolveMountClaims(featureList, options)
+  if (!claims.ok) errors.push(...claims.errors)
+
+  const installedViews = new Set(
+    views.filter((view) => isPlainObject(view) && typeof view.name === 'string').map((view) => view.name)
+  )
+
+  for (const viewName of installedViews) {
+    const owner = features.features.find(
+      (feature) => Array.isArray(feature.views) && feature.views.includes(viewName)
+    )
+    if (owner && !installedFeatures.has(owner.name)) {
+      errors.push(
+        `View "${viewName}" is owned by feature "${owner.name}" and cannot be installed directly. Run \`storefront feature add ${owner.name}\` instead.`
+      )
+    }
+  }
+
+  for (const featureName of installedFeatures) {
+    const owned = getFeature(featureName)?.views
+    for (const viewName of Array.isArray(owned) ? owned : []) {
+      if (!installedViews.has(viewName)) {
         errors.push(
-          `Section variant "${section.variant}" is not allowed for section "${section.name}". Allowed: ${def.variants.join(', ')}.`
+          `Feature "${featureName}" requires view "${viewName}", which is not installed. Run \`storefront feature add ${featureName}\` to install it.`
         )
       }
     }
@@ -179,8 +975,18 @@ function main() {
     return
   }
 
+  if (command === 'sections') {
+    const errors = sectionStatusErrors()
+    if (errors.length > 0) {
+      console.error(errors.join('\n'))
+      process.exit(1)
+    }
+    console.log(JSON.stringify(sectionRegistry(), null, 2))
+    return
+  }
+
   console.error(
-    'Usage: validate.mjs list | show <view> | validate <composition.json> | resolve <view> <slot> <intent> | archetypes'
+    'Usage: validate.mjs list | show <view> | validate <composition.json> | resolve <view> <slot> <intent> | archetypes | sections'
   )
   process.exit(1)
 }