@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/operations.mjs

@@ -0,0 +1,720 @@
+#!/usr/bin/env node
+// Composition operation registry and desired-state reducer (E1 task 4.1).
+//
+// This module is the single authority for the six public composition operations
+// and for the pure manifest reduction they describe. `plan`/`apply` and the
+// legacy `view add|remove` / `feature add|remove` aliases all reduce through
+// `reduceManifest`, so an alias and its plan/apply equivalent mutate the same
+// manifest and emit the same diagnostics.
+//
+// It is pure over its arguments: it reads the registry through
+// `recipes/validate.mjs` and never touches the filesystem. Writing derived files
+// and the manifest is owned by `plan-apply.mjs`.
+//
+// Envelope: `{ "formatVersion": 1, "operations": [...] }`. A missing or
+// non-1 version is `E_INVALID_ENVELOPE`; an operation name outside the six is
+// `E_UNKNOWN_OPERATION`. The registry is namespaced and extensible — later
+// changes add namespaced operations without redefining these names (Decision 16).
+//
+// The six closed operation field schemas are declared by `OPERATION_SCHEMAS`
+// (required + optional fields per operation); this module is their runtime
+// authority. The same contract is published as `recipes/operations.schema.json`
+// (E1 task 4.10). The canonical field order is read from the active registry
+// (`scripts/operation-registry.mjs`), so there is one source of the operation
+// vocabulary.
+//
+// Whole-plan diagnostics (E1 task 4.3): `parseOperationsEnvelope` collects every
+// malformed/unknown operation instead of stopping at the first, and
+// `reduceManifest` validates every operation against the resulting complete
+// state and reports all diagnostics. A caller that sees any diagnostic MUST NOT
+// emit a plan or write anything, so a single invalid operation never leaves a
+// partially valid plan or a mutated project.
+
+import {
+  allowedFeatureNames,
+  allowedViewNames,
+  featureConfigRejectionFor,
+  getCatalogVariant,
+  getFeature,
+  isAllowedVariant,
+  isSupportedVariant,
+  normalizeFeatureConfig,
+  resolveIntent,
+  resolveMountClaims,
+} from '../recipes/validate.mjs'
+import { MANIFEST_FILE, normalizeFeature, normalizeView } from './manifest.mjs'
+import {
+  createOperationRegistry,
+  extendOperationRegistry,
+  operationFieldOrder,
+  operationNames,
+  operationReducer,
+  operationSchema,
+} from './operation-registry.mjs'
+import { CATALOG_LOGICAL_CONTROLS } from './logical-controls.mjs'
+import { preflightManifest } from './preflight.mjs'
+
+export const OPERATIONS_FORMAT_VERSION = 1
+
+// E1 registers exactly these six namespaced operations (E1 design Decision 16).
+// Each `reducer` is the behavior; the reducer functions are hoisted declarations
+// below, so the registry is built once at module load. `OPERATION_NAMES` and
+// `OPERATION_SCHEMAS` are derived from this registry, so the operation
+// vocabulary has exactly one source.
+//
+// EXTENSIBILITY (E1 task 4.15): the registry is a seam, not a freeze. A later
+// change (E2's logical controls, E3's `section.*`) builds a new registry with
+// `extendOperationRegistry` and threads it through `options.registry`; the E1
+// registry and its six names are never mutated, and production rejects any
+// operation outside the six with `E_UNKNOWN_OPERATION`. See
+// `scripts/operation-registry.mjs`.
+export const E1_OPERATION_REGISTRY = createOperationRegistry({
+  operations: [
+    {
+      name: 'view.add',
+      required: ['view'],
+      optional: ['intents', 'variants'],
+      reducer: reduceViewAdd,
+    },
+    { name: 'view.remove', required: ['view'], optional: [], reducer: reduceViewRemove },
+    {
+      name: 'view.configure',
+      required: ['view', 'slot'],
+      optional: ['intent', 'variant', 'reset'],
+      reducer: reduceViewConfigure,
+    },
+    { name: 'feature.add', required: ['feature'], optional: ['config'], reducer: reduceFeatureAdd },
+    { name: 'feature.remove', required: ['feature'], optional: [], reducer: reduceFeatureRemove },
+    {
+      name: 'feature.configure',
+      required: ['feature', 'config'],
+      optional: [],
+      reducer: reduceFeatureConfigure,
+    },
+  ],
+})
+
+// The closed E1 operation names, derived from the registry. Any other `op` is
+// rejected with `E_UNKNOWN_OPERATION`; later changes extend the registry without
+// changing these names.
+export const OPERATION_NAMES = Object.freeze(operationNames(E1_OPERATION_REGISTRY))
+
+// E2 task 6.1: the production registry E2's generation consumes — E1's six
+// operations plus the two catalog logical controls. It is a NEW frozen registry;
+// `E1_OPERATION_REGISTRY` is never widened, so E1's public operation vocabulary
+// and its empty logical-controls set are unchanged.
+export const CATALOG_OPERATION_REGISTRY = extendOperationRegistry(E1_OPERATION_REGISTRY, {
+  logicalControls: CATALOG_LOGICAL_CONTROLS,
+})
+
+export const DIAGNOSTIC_CODES = Object.freeze({
+  E_INVALID_ENVELOPE: 'E_INVALID_ENVELOPE',
+  E_INVALID_OPERATION: 'E_INVALID_OPERATION',
+  E_UNKNOWN_OPERATION: 'E_UNKNOWN_OPERATION',
+  E_UNKNOWN_VIEW: 'E_UNKNOWN_VIEW',
+  E_UNKNOWN_FEATURE: 'E_UNKNOWN_FEATURE',
+  E_VIEW_NOT_INSTALLED: 'E_VIEW_NOT_INSTALLED',
+  E_FEATURE_NOT_INSTALLED: 'E_FEATURE_NOT_INSTALLED',
+  E_VIEW_ALREADY_INSTALLED: 'E_VIEW_ALREADY_INSTALLED',
+  E_FEATURE_ALREADY_INSTALLED: 'E_FEATURE_ALREADY_INSTALLED',
+  E_HELD_VARIANT: 'E_HELD_VARIANT',
+  E_INVALID_COMPOSITION: 'E_INVALID_COMPOSITION',
+  E_CONFIG_INVALID: 'E_CONFIG_INVALID',
+  E_UNPROVEN_CHECKOUT_OPTION: 'E_UNPROVEN_CHECKOUT_OPTION',
+  E_SLOT_OWNED_BY_INSTANCE: 'E_SLOT_OWNED_BY_INSTANCE',
+  E_OWNERSHIP_CONFLICT: 'E_OWNERSHIP_CONFLICT',
+})
+
+// The six closed operation field schemas: the required and optional fields of
+// each operation (E1 task 4.10). Derived from the E1 registry so the vocabulary
+// has exactly one source. `required` is enforced by the reducers (which reject a
+// missing field with `E_INVALID_OPERATION`); `optional` is the closed allow-list.
+// This is the single authority the published `recipes/operations.schema.json`
+// mirrors.
+export const OPERATION_SCHEMAS = Object.freeze(
+  Object.fromEntries(
+    OPERATION_NAMES.map((op) => {
+      const schema = operationSchema(E1_OPERATION_REGISTRY, op)
+      return [
+        op,
+        Object.freeze({
+          required: Object.freeze([...schema.required]),
+          optional: Object.freeze([...schema.optional]),
+        }),
+      ]
+    }),
+  ),
+)
+
+// The closed set of envelope-level fields. `$schema` is the optional JSON-schema
+// self-description (matching `recipes/operations.schema.json`); anything else is
+// an unknown top-level field and is rejected with `E_INVALID_ENVELOPE`.
+const ENVELOPE_FIELDS = Object.freeze(['$schema', 'formatVersion', 'operations'])
+
+// The allowed fields of one operation: `op` plus its declared required and
+// optional fields, read from the active registry. Used at the untrusted boundary
+// to reject an unknown field or a field that belongs to a different operation
+// (E1 task 4.10).
+function operationFieldSet(registry, op) {
+  return new Set(['op', ...operationFieldOrder(registry, op)])
+}
+
+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 diagnostic(code, message, extra = {}) {
+  return { code, severity: 'error', message, ...extra }
+}
+
+function preflightDiagnostics(errors) {
+  return errors.map((message) => diagnostic(DIAGNOSTIC_CODES.E_INVALID_COMPOSITION, message))
+}
+
+// Recursively sort object keys so a serialized operation is byte-stable for the
+// same logical input, regardless of the caller's key insertion order.
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue)
+  if (isPlainObject(value)) {
+    const out = {}
+    for (const key of Object.keys(value).sort()) out[key] = sortValue(value[key])
+    return out
+  }
+  return value
+}
+
+/**
+ * Canonicalize one operation: fixed field order, sorted nested maps. This is a
+ * TRUSTED helper — it assumes the operation already passed the boundary check in
+ * `parseOperationsEnvelope`, so an unknown field is stripped rather than
+ * reported. Never call it on untrusted input directly (E1 task 4.10).
+ *
+ * `options.registry` selects the active registry (defaults to E1's); a later
+ * change canonicalizes its namespaced operations against its own registry
+ * without touching E1's names.
+ */
+export function canonicalOperation(op, options = {}) {
+  const registry = options.registry ?? E1_OPERATION_REGISTRY
+  const out = { op: op.op }
+  for (const field of operationFieldOrder(registry, op.op)) {
+    if (hasOwn(op, field)) out[field] = sortValue(op[field])
+  }
+  return out
+}
+
+export function canonicalOperations(operations, options = {}) {
+  return operations.map((op) => canonicalOperation(op, options))
+}
+
+/**
+ * Validate and canonicalize an operations envelope. Returns
+ * `{ ok, operations, diagnostics }`. On an envelope-level failure (not an
+ * object, wrong `formatVersion`, an unknown top-level field, or a non-array
+ * `operations`) `operations` is empty because the envelope cannot be interpreted
+ * at all. When individual operations are malformed, unknown, or carry a field
+ * outside their closed per-operation schema, they are reported and skipped while
+ * the remaining valid operations are still returned, so a caller can combine
+ * parse-level and semantic diagnostics in one pass (E1 tasks 4.3, 4.10). `ok` is
+ * true only when there are no diagnostics.
+ *
+ * This is the untrusted boundary: the active registry's per-operation field
+ * schemas are closed here, so an unknown field, a field belonging to a different
+ * operation, or a public `force: true` is rejected with `E_INVALID_OPERATION`
+ * before any canonicalization or write.
+ *
+ * `options.registry` selects the active registry (defaults to E1's). E1's six
+ * names and diagnostics are unchanged; a later change passes its own registry to
+ * accept its namespaced operations and reject the rest with
+ * `E_UNKNOWN_OPERATION`.
+ */
+export function parseOperationsEnvelope(raw, options = {}) {
+  const registry = options.registry ?? E1_OPERATION_REGISTRY
+  if (!isPlainObject(raw)) {
+    return {
+      ok: false,
+      operations: [],
+      diagnostics: [
+        diagnostic(DIAGNOSTIC_CODES.E_INVALID_ENVELOPE, 'operations envelope must be a JSON object.'),
+      ],
+    }
+  }
+  const envelopeDiagnostics = []
+  if (raw.formatVersion !== OPERATIONS_FORMAT_VERSION) {
+    envelopeDiagnostics.push(
+      diagnostic(
+        DIAGNOSTIC_CODES.E_INVALID_ENVELOPE,
+        `operations envelope formatVersion must be ${OPERATIONS_FORMAT_VERSION} (got ${JSON.stringify(raw.formatVersion)}).`,
+      ),
+    )
+  }
+  for (const key of Object.keys(raw)) {
+    if (!ENVELOPE_FIELDS.includes(key)) {
+      envelopeDiagnostics.push(
+        diagnostic(
+          DIAGNOSTIC_CODES.E_INVALID_ENVELOPE,
+          `operations envelope has unknown top-level field "${key}". Allowed fields: ${ENVELOPE_FIELDS.join(', ')}.`,
+          { path: key, detail: { field: key, allowed: [...ENVELOPE_FIELDS] } },
+        ),
+      )
+    }
+  }
+  if (!Array.isArray(raw.operations)) {
+    envelopeDiagnostics.push(
+      diagnostic(
+        DIAGNOSTIC_CODES.E_INVALID_ENVELOPE,
+        'operations envelope must declare an "operations" array.',
+      ),
+    )
+  }
+  if (envelopeDiagnostics.length > 0) {
+    return { ok: false, operations: [], diagnostics: envelopeDiagnostics }
+  }
+  const operations = []
+  const diagnostics = []
+  for (let index = 0; index < raw.operations.length; index++) {
+    const op = raw.operations[index]
+    if (!isPlainObject(op) || typeof op.op !== 'string' || op.op.length === 0) {
+      diagnostics.push(
+        diagnostic(
+          DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+          `operation[${index}] must be an object with a non-empty string "op".`,
+          { path: `operations[${index}]` },
+        ),
+      )
+      continue
+    }
+    if (!operationNames(registry).includes(op.op)) {
+      diagnostics.push(
+        diagnostic(
+          DIAGNOSTIC_CODES.E_UNKNOWN_OPERATION,
+          `Unknown operation "${op.op}". E1 implements: ${OPERATION_NAMES.join(', ')}.`,
+          { path: `operations[${index}]`, detail: { op: op.op } },
+        ),
+      )
+      continue
+    }
+    // Closed per-operation field schema (E1 task 4.10): an unknown field or a
+    // field belonging to another operation is rejected before canonicalization.
+    const allowed = operationFieldSet(registry, op.op)
+    const unknown = Object.keys(op).filter((key) => !allowed.has(key))
+    if (unknown.length > 0) {
+      for (const key of unknown) {
+        diagnostics.push(
+          diagnostic(
+            DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+            `operation[${index}] (${op.op}) has unknown field "${key}". Allowed fields: ${[...allowed].join(', ')}.`,
+            {
+              path: `operations[${index}].${key}`,
+              detail: { op: op.op, field: key, allowed: [...allowed] },
+            },
+          ),
+        )
+      }
+      continue
+    }
+    operations.push(canonicalOperation(op, { registry }))
+  }
+  return { ok: diagnostics.length === 0, operations, diagnostics }
+}
+
+function requireString(op, field) {
+  return typeof op[field] === 'string' && op[field].length > 0
+}
+
+function fail(code, message) {
+  return { ok: false, diagnostics: [diagnostic(code, message)] }
+}
+
+// Shared host-slot ownership check (E1 task 3.8 / CU-05, CU-06). While an
+// installed feature instance claims a host slot, the instance's `config` is the
+// single presentation truth for that slot: a direct selection or reset of the
+// slot is rejected with `E_SLOT_OWNED_BY_INSTANCE` and nothing is written. The
+// view's stored selection stays dormant (never cleared) so removing the instance
+// restores it. Claims are resolved through the single registry authority
+// (`resolveMountClaims`), so the alias commands, plan/apply, and generation all
+// read one resolved claim set; `options.getFeatureSpec` is the hermetic
+// injection seam a test uses without shipping a generic conflicting feature.
+function claimedSlots(manifest, options = {}) {
+  const features = Array.isArray(manifest?.features) ? manifest.features : []
+  return resolveMountClaims(features, options).claims
+}
+
+function slotOwnedByInstanceDiagnostic(host, slot, claim) {
+  return diagnostic(
+    DIAGNOSTIC_CODES.E_SLOT_OWNED_BY_INSTANCE,
+    `Slot "${host}.${slot}" is claimed by the installed feature instance "${claim.featureName}" (mount "${claim.id}"); the feature config is the only source of that slot's presentation. Configure the feature instead, or remove it to restore the view's stored selection.`,
+    {
+      path: MANIFEST_FILE,
+      detail: { host, slot, feature: claim.featureName, mountId: claim.id },
+    },
+  )
+}
+
+// Feature config failures keep their declared stable code (E1 task 3.5 /
+// Decision 12): a feature that declares a `configRejection` (checkout) reports
+// its own code for any non-empty config, and a recognized feature whose config
+// violates its contract reports `E_CONFIG_INVALID`. A structural malformation
+// (a `config` that is not an object) is rejected earlier as
+// `E_INVALID_OPERATION`. The human message is `normalizeFeatureConfig`'s
+// unchanged text, so the existing CLI wording is preserved; the structured code
+// and metadata ride alongside it.
+function featureConfigDiagnostic(name, normalized, requested) {
+  const rejection = featureConfigRejectionFor(name, requested)
+  const rejectedKeys =
+    isPlainObject(requested) && Object.keys(requested).length > 0 ? Object.keys(requested) : []
+  if (rejection) {
+    return diagnostic(rejection.code, normalized.errors.join(' '), {
+      path: MANIFEST_FILE,
+      detail: { feature: name, rejectedKeys },
+    })
+  }
+  return diagnostic(DIAGNOSTIC_CODES.E_CONFIG_INVALID, normalized.errors.join(' '), {
+    path: MANIFEST_FILE,
+    detail: { feature: name },
+  })
+}
+
+function reduceViewAdd(manifest, op, ctx) {
+  const name = op.view
+  if (!requireString(op, 'view')) {
+    return fail(DIAGNOSTIC_CODES.E_INVALID_OPERATION, 'view.add requires a non-empty string "view".')
+  }
+  if (!allowedViewNames().includes(name)) {
+    return fail(
+      DIAGNOSTIC_CODES.E_UNKNOWN_VIEW,
+      `Unknown view "${name}". Allowed views: ${allowedViewNames().join(', ')}.`,
+    )
+  }
+  const present = manifest.views.some((view) => view.name === name)
+  // Copy the caller's maps so the dormant-selection merge below never mutates
+  // the canonical operation object.
+  const intents = { ...(isPlainObject(op.intents) ? op.intents : {}) }
+  const variants = { ...(isPlainObject(op.variants) ? op.variants : {}) }
+
+  // A held variant can never render; reject it before any structural check so
+  // the diagnostic names the variant and its catalog reason (CU-07), even when
+  // the view is already installed and `--force` was not given.
+  for (const [slot, variant] of Object.entries(variants)) {
+    const held = getCatalogVariant(name, slot, variant)
+    if (held?.status === 'held') {
+      return fail(
+        DIAGNOSTIC_CODES.E_HELD_VARIANT,
+        `Variant "${variant}" is held for ${name}.${slot} and not supported by the curated MVP set: ${held.reason}.`,
+      )
+    }
+  }
+  if (present && !ctx.force) {
+    return fail(
+      DIAGNOSTIC_CODES.E_VIEW_ALREADY_INSTALLED,
+      `View "${name}" is already installed. Use --force to re-add it.`,
+    )
+  }
+  // One presentation truth per slot (E1 task 3.8): a `view.add` that explicitly
+  // selects an instance-claimed slot is a direct configuration of that slot and
+  // is rejected, matching `view.configure`. Claims resolve through the single
+  // registry authority.
+  const claims = claimedSlots(manifest, ctx)
+  for (const slot of [...Object.keys(intents), ...Object.keys(variants)]) {
+    const claim = claims.get(`${name}.${slot}`)
+    if (claim) {
+      return { ok: false, diagnostics: [slotOwnedByInstanceDiagnostic(name, slot, claim)] }
+    }
+  }
+  for (const [slot, intent] of Object.entries(intents)) {
+    const resolved = resolveIntent(name, slot, intent)
+    if (!resolved.ok) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        `Invalid intent for ${name}.${slot}: ${resolved.errors.join(' ')}`,
+      )
+    }
+  }
+  for (const [slot, variant] of Object.entries(variants)) {
+    if (!isAllowedVariant(name, slot, variant)) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        `Variant "${variant}" is not allowed for ${name}.${slot}.`,
+      )
+    }
+  }
+  // Retain the dormant stored selection of a claimed slot the operation does not
+  // touch, so a `view.add --force` can never silently clear it while an instance
+  // owns the slot (E1 task 3.8). Non-claimed slots keep the documented
+  // "omitted selection -> recipe defaults" behavior.
+  if (present) {
+    const existing = manifest.views.find((view) => view.name === name)
+    for (const claim of claims.values()) {
+      if (claim.host !== name) continue
+      if (hasOwn(intents, claim.slot) || hasOwn(variants, claim.slot)) continue
+      if (hasOwn(existing.intents ?? {}, claim.slot)) intents[claim.slot] = existing.intents[claim.slot]
+      else if (hasOwn(existing.variants ?? {}, claim.slot)) {
+        variants[claim.slot] = existing.variants[claim.slot]
+      }
+    }
+  }
+  const entry = normalizeView({ name, intents, variants })
+  const views = present
+    ? manifest.views.map((view) => (view.name === name ? entry : view))
+    : [...manifest.views, entry]
+  return { ok: true, manifest: { ...manifest, views } }
+}
+
+function reduceViewRemove(manifest, op) {
+  const name = op.view
+  if (!requireString(op, 'view')) {
+    return fail(DIAGNOSTIC_CODES.E_INVALID_OPERATION, 'view.remove requires a non-empty string "view".')
+  }
+  if (!allowedViewNames().includes(name)) {
+    return fail(
+      DIAGNOSTIC_CODES.E_UNKNOWN_VIEW,
+      `Unknown view "${name}". Allowed views: ${allowedViewNames().join(', ')}.`,
+    )
+  }
+  if (!manifest.views.some((view) => view.name === name)) {
+    return fail(DIAGNOSTIC_CODES.E_VIEW_NOT_INSTALLED, `View "${name}" is not installed.`)
+  }
+  return {
+    ok: true,
+    manifest: { ...manifest, views: manifest.views.filter((view) => view.name !== name) },
+    removals: [{ kind: 'view', name }],
+  }
+}
+
+function reduceViewConfigure(manifest, op, ctx) {
+  const name = op.view
+  if (!requireString(op, 'view')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'view.configure requires a non-empty string "view".',
+    )
+  }
+  if (!requireString(op, 'slot')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'view.configure requires a non-empty string "slot".',
+    )
+  }
+  const index = manifest.views.findIndex((view) => view.name === name)
+  if (index === -1) {
+    return fail(DIAGNOSTIC_CODES.E_VIEW_NOT_INSTALLED, `View "${name}" is not installed.`)
+  }
+  const selectors = ['intent', 'variant'].filter((field) => hasOwn(op, field)).length
+  const reset = op.reset === true
+  if (selectors + (reset ? 1 : 0) !== 1) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'view.configure requires exactly one of "intent", "variant", or "reset": true.',
+    )
+  }
+  // One presentation truth per slot (E1 task 3.8 / CU-05, CU-06): while an
+  // installed feature instance claims the slot, its feature config is the only
+  // source of the slot's presentation. A direct selection OR reset of that slot
+  // is rejected and nothing is written; the view's stored selection stays
+  // dormant. Claims resolve through the single registry authority.
+  const claim = claimedSlots(manifest, ctx).get(`${name}.${op.slot}`)
+  if (claim) {
+    return { ok: false, diagnostics: [slotOwnedByInstanceDiagnostic(name, op.slot, claim)] }
+  }
+  const view = manifest.views[index]
+  const intents = { ...view.intents }
+  const variants = { ...view.variants }
+  if (hasOwn(op, 'intent')) {
+    const resolved = resolveIntent(name, op.slot, op.intent)
+    if (!resolved.ok) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        `Invalid intent for ${name}.${op.slot}: ${resolved.errors.join(' ')}`,
+      )
+    }
+    if (!isSupportedVariant(name, op.slot, resolved.variant)) {
+      return fail(
+        DIAGNOSTIC_CODES.E_HELD_VARIANT,
+        `Intent "${op.intent}" resolves to "${resolved.variant}", which is not executable for ${name}.${op.slot}.`,
+      )
+    }
+    intents[op.slot] = op.intent
+    delete variants[op.slot]
+  } else if (hasOwn(op, 'variant')) {
+    const held = getCatalogVariant(name, op.slot, op.variant)
+    if (held?.status === 'held') {
+      return fail(
+        DIAGNOSTIC_CODES.E_HELD_VARIANT,
+        `Variant "${op.variant}" is held for ${name}.${op.slot} and not supported by the curated MVP set: ${held.reason}.`,
+      )
+    }
+    if (!isSupportedVariant(name, op.slot, op.variant)) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        `Variant "${op.variant}" is not executable for ${name}.${op.slot}.`,
+      )
+    }
+    variants[op.slot] = op.variant
+    delete intents[op.slot]
+  } else {
+    delete intents[op.slot]
+    delete variants[op.slot]
+  }
+  const views = manifest.views.map((entry, entryIndex) =>
+    entryIndex === index ? { ...entry, intents, variants } : entry,
+  )
+  return { ok: true, manifest: { ...manifest, views } }
+}
+
+function reduceFeatureAdd(manifest, op, ctx) {
+  const name = op.feature
+  if (!requireString(op, 'feature')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'feature.add requires a non-empty string "feature".',
+    )
+  }
+  if (!allowedFeatureNames().includes(name)) {
+    return fail(
+      DIAGNOSTIC_CODES.E_UNKNOWN_FEATURE,
+      `Unknown feature "${name}". Allowed features: ${allowedFeatureNames().join(', ')}.`,
+    )
+  }
+  const present = manifest.features.some((feature) => feature.name === name)
+  if (present && !ctx.force) {
+    return fail(
+      DIAGNOSTIC_CODES.E_FEATURE_ALREADY_INSTALLED,
+      `Feature "${name}" is already installed. Use --force to re-add it.`,
+    )
+  }
+  // A re-add without an explicit config preserves the installed config; a fresh
+  // add seeds the feature's declared defaults (E1 task 3.1).
+  const existingConfig = present
+    ? (manifest.features.find((feature) => feature.name === name)?.config ?? {})
+    : {}
+  const requested = hasOwn(op, 'config') ? op.config : existingConfig
+  const normalized = normalizeFeatureConfig(name, isPlainObject(requested) ? requested : {})
+  if (!normalized.ok) {
+    return { ok: false, diagnostics: [featureConfigDiagnostic(name, normalized, requested)] }
+  }
+  const entry = normalizeFeature({ name, config: normalized.config })
+  const features = present
+    ? manifest.features.map((feature) => (feature.name === name ? entry : feature))
+    : [...manifest.features, entry]
+  const owned = getFeature(name)?.views ?? []
+  const views = [...manifest.views]
+  for (const viewName of owned) {
+    if (!views.some((view) => view.name === viewName)) views.push(normalizeView(viewName))
+  }
+  return { ok: true, manifest: { ...manifest, features, views } }
+}
+
+function reduceFeatureRemove(manifest, op) {
+  const name = op.feature
+  if (!requireString(op, 'feature')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'feature.remove requires a non-empty string "feature".',
+    )
+  }
+  if (!allowedFeatureNames().includes(name)) {
+    return fail(
+      DIAGNOSTIC_CODES.E_UNKNOWN_FEATURE,
+      `Unknown feature "${name}". Allowed features: ${allowedFeatureNames().join(', ')}.`,
+    )
+  }
+  if (!manifest.features.some((feature) => feature.name === name)) {
+    return fail(DIAGNOSTIC_CODES.E_FEATURE_NOT_INSTALLED, `Feature "${name}" is not installed.`)
+  }
+  const features = manifest.features.filter((feature) => feature.name !== name)
+  const stillOwned = new Set(features.flatMap((feature) => getFeature(feature.name)?.views ?? []))
+  const removedViews = (getFeature(name)?.views ?? []).filter((view) => !stillOwned.has(view))
+  const views = manifest.views.filter((view) => !removedViews.includes(view.name))
+  const removals = [{ kind: 'feature', name }]
+  for (const view of removedViews) removals.push({ kind: 'view', name: view })
+  return { ok: true, manifest: { ...manifest, features, views }, removals }
+}
+
+function reduceFeatureConfigure(manifest, op) {
+  const name = op.feature
+  if (!requireString(op, 'feature')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'feature.configure requires a non-empty string "feature".',
+    )
+  }
+  if (!manifest.features.some((feature) => feature.name === name)) {
+    return fail(DIAGNOSTIC_CODES.E_FEATURE_NOT_INSTALLED, `Feature "${name}" is not installed.`)
+  }
+  if (!isPlainObject(op.config)) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'feature.configure requires a "config" object.',
+    )
+  }
+  // REPLACE semantics: the provided config is validated and its declared
+  // defaults seeded; it fully replaces the installed config.
+  const normalized = normalizeFeatureConfig(name, op.config)
+  if (!normalized.ok) {
+    return { ok: false, diagnostics: [featureConfigDiagnostic(name, normalized, op.config)] }
+  }
+  const features = manifest.features.map((feature) =>
+    feature.name === name ? normalizeFeature({ name, config: normalized.config }) : feature,
+  )
+  return { ok: true, manifest: { ...manifest, features } }
+}
+
+/**
+ * Reduce a manifest through an ordered operation list into the complete desired
+ * state (E1 task 4.3). Validates the input composition, then every operation
+ * against the resulting state as it evolves, then the whole resulting
+ * composition before returning. Unlike a first-failure reducer, this collects
+ * the diagnostics of every invalid operation — an unknown name, an invalid
+ * field, a held variant, a claim conflict, or a final-composition error — so a
+ * caller can report all errors in one pass.
+ *
+ * An invalid operation is recorded and skipped; the remaining operations still
+ * reduce against the last valid state, so independent errors are all reported
+ * and a valid operation sequence (for example a `view.remove` followed by a
+ * `view.add` that restores it) is validated in order. A caller MUST NOT emit a
+ * plan or write when `ok` is false. Returns
+ * `{ ok, manifest, diagnostics, removals }`; on failure `manifest` is the
+ * original input and `removals` is empty.
+ *
+ * `options.force` allows re-adding an already-installed unit (the legacy
+ * `--force` flag); `plan`/`apply` reduce with `force: true` because their
+ * `*.add` operations are defined as add/refresh. `options.getFeatureSpec` is the
+ * hermetic registry injection seam used by tests. `options.registry` selects the
+ * active operation registry (defaults to E1's six), so a later change dispatches
+ * its own namespaced reducers through the same whole-state engine.
+ */
+export function reduceManifest(manifest, operations, options = {}) {
+  const registry = options.registry ?? E1_OPERATION_REGISTRY
+  const input = preflightManifest(manifest, options)
+  if (!input.ok) {
+    return { ok: false, manifest, diagnostics: preflightDiagnostics(input.errors), removals: [] }
+  }
+  let next = structuredClone(manifest)
+  const diagnostics = []
+  const removals = []
+  for (const op of operations) {
+    const reducer = operationReducer(registry, op.op)
+    if (!reducer) {
+      diagnostics.push(
+        diagnostic(DIAGNOSTIC_CODES.E_UNKNOWN_OPERATION, `Unknown operation "${op.op}".`),
+      )
+      continue
+    }
+    const result = reducer(next, op, options)
+    if (!result.ok) {
+      diagnostics.push(...result.diagnostics)
+      continue
+    }
+    next = result.manifest
+    if (Array.isArray(result.removals)) removals.push(...result.removals)
+  }
+  const final = preflightManifest(next, options)
+  if (!final.ok) diagnostics.push(...preflightDiagnostics(final.errors))
+  if (diagnostics.length > 0) {
+    return { ok: false, manifest, diagnostics, removals: [] }
+  }
+  return { ok: true, manifest: next, diagnostics: [], removals }
+}