@contractspec/lib.surface-runtime 0.2.0

package/dist/evals/golden-harness.js

@@ -0,0 +1,849 @@
+// @bun
+// src/telemetry/surface-metrics.ts
+import {
+  createCounter,
+  createHistogram
+} from "@contractspec/lib.observability/metrics";
+var METER_NAME = "@contractspec/lib.surface-runtime";
+var resolutionDurationMs = createHistogram("bundle_surface_resolution_duration_ms", "Time to resolve bundle spec to surface plan in milliseconds", METER_NAME);
+var patchAcceptanceCounter = createCounter("bundle_surface_patch_acceptance_total", "Total AI patch proposals accepted by user", METER_NAME);
+var patchRejectionCounter = createCounter("bundle_surface_patch_rejection_total", "Total AI patch proposals rejected by user", METER_NAME);
+var policyDenialCounter = createCounter("bundle_surface_policy_denial_total", "Total policy denials (actions denied by policy)", METER_NAME);
+var surfaceFallbackCounter = createCounter("bundle_surface_fallback_total", "Total surface or layout fallbacks during resolution", METER_NAME);
+var missingRendererCounter = createCounter("bundle_surface_renderer_missing_total", "Total slots with no renderer for requested node kind", METER_NAME);
+// src/runtime/resolve-preferences.ts
+var DIMENSION_KEYS = [
+  "guidance",
+  "density",
+  "dataDepth",
+  "control",
+  "media",
+  "pace",
+  "narrative"
+];
+var SCOPE_ORDER = [
+  "user",
+  "workspace-user",
+  "bundle",
+  "surface",
+  "entity",
+  "session"
+];
+function mergeByScope(layers, ctx) {
+  const merged = { ...ctx.preferences };
+  const sourceByDimension = {};
+  for (const scope of SCOPE_ORDER) {
+    const layer = layers[scope];
+    if (!layer)
+      continue;
+    for (const dim of DIMENSION_KEYS) {
+      const val = layer[dim];
+      if (val !== undefined) {
+        merged[dim] = val;
+        sourceByDimension[dim] = scope;
+      }
+    }
+  }
+  for (const dim of DIMENSION_KEYS) {
+    if (sourceByDimension[dim] === undefined) {
+      sourceByDimension[dim] = "session";
+    }
+  }
+  return { canonical: merged, sourceByDimension };
+}
+function resolveConstraints(_canonical, _ctx) {
+  return { constrained: {}, notes: [] };
+}
+function resolvePreferenceProfile(ctx) {
+  const layers = {
+    session: ctx.preferences
+  };
+  const { canonical, sourceByDimension } = mergeByScope(layers, ctx);
+  const { constrained, notes } = resolveConstraints(canonical, ctx);
+  return {
+    canonical,
+    sourceByDimension,
+    constrained,
+    notes
+  };
+}
+
+// src/spec/validate-surface-patch.ts
+var VALID_OPS = [
+  "insert-node",
+  "replace-node",
+  "remove-node",
+  "move-node",
+  "resize-panel",
+  "set-layout",
+  "reveal-field",
+  "hide-field",
+  "promote-action",
+  "set-focus"
+];
+var VALID_NODE_KINDS = [
+  "metric-strip",
+  "data-view",
+  "entity-card",
+  "entity-header",
+  "entity-summary",
+  "entity-section",
+  "entity-field",
+  "entity-activity",
+  "entity-relations",
+  "entity-timeline",
+  "entity-comments",
+  "entity-attachments",
+  "entity-view-switcher",
+  "entity-automation-panel",
+  "rich-doc",
+  "chat-thread",
+  "assistant-panel",
+  "action-bar",
+  "timeline",
+  "board",
+  "table",
+  "calendar",
+  "form",
+  "chart",
+  "relation-graph",
+  "custom-widget"
+];
+function validateSurfaceNode(node, path) {
+  if (!node.nodeId || typeof node.nodeId !== "string") {
+    throw new Error(`${path}: nodeId must be a non-empty string`);
+  }
+  if (!node.kind || !VALID_NODE_KINDS.includes(node.kind)) {
+    throw new Error(`${path}: kind must be one of ${VALID_NODE_KINDS.join(", ")}`);
+  }
+  if (node.children) {
+    for (let i = 0;i < node.children.length; i++) {
+      const child = node.children[i];
+      if (child)
+        validateSurfaceNode(child, `${path}.children[${i}]`);
+    }
+  }
+}
+function validateSurfacePatchOp(op, index) {
+  const path = `ops[${index}]`;
+  if (!op || typeof op !== "object" || !("op" in op)) {
+    throw new Error(`${path}: must be an object with op field`);
+  }
+  const opType = op.op;
+  if (!VALID_OPS.includes(opType)) {
+    throw new Error(`${path}: op must be one of ${VALID_OPS.join(", ")}`);
+  }
+  switch (op.op) {
+    case "insert-node":
+      if (!op.slotId || typeof op.slotId !== "string") {
+        throw new Error(`${path}: insert-node requires slotId string`);
+      }
+      if (!op.node) {
+        throw new Error(`${path}: insert-node requires node`);
+      }
+      validateSurfaceNode(op.node, `${path}.node`);
+      if (op.index !== undefined && typeof op.index !== "number") {
+        throw new Error(`${path}: insert-node index must be number if present`);
+      }
+      break;
+    case "replace-node":
+      if (!op.nodeId || typeof op.nodeId !== "string") {
+        throw new Error(`${path}: replace-node requires nodeId string`);
+      }
+      if (!op.node) {
+        throw new Error(`${path}: replace-node requires node`);
+      }
+      validateSurfaceNode(op.node, `${path}.node`);
+      break;
+    case "remove-node":
+      if (!op.nodeId || typeof op.nodeId !== "string") {
+        throw new Error(`${path}: remove-node requires nodeId string`);
+      }
+      break;
+    case "move-node":
+      if (!op.nodeId || typeof op.nodeId !== "string") {
+        throw new Error(`${path}: move-node requires nodeId string`);
+      }
+      if (!op.toSlotId || typeof op.toSlotId !== "string") {
+        throw new Error(`${path}: move-node requires toSlotId string`);
+      }
+      if (op.index !== undefined && typeof op.index !== "number") {
+        throw new Error(`${path}: move-node index must be number if present`);
+      }
+      break;
+    case "resize-panel":
+      if (!op.persistKey || typeof op.persistKey !== "string") {
+        throw new Error(`${path}: resize-panel requires persistKey string`);
+      }
+      if (!Array.isArray(op.sizes) || op.sizes.some((s) => typeof s !== "number")) {
+        throw new Error(`${path}: resize-panel requires sizes number[]`);
+      }
+      break;
+    case "set-layout":
+      if (!op.layoutId || typeof op.layoutId !== "string") {
+        throw new Error(`${path}: set-layout requires layoutId string`);
+      }
+      break;
+    case "reveal-field":
+    case "hide-field":
+      if (!op.fieldId || typeof op.fieldId !== "string") {
+        throw new Error(`${path}: ${op.op} requires fieldId string`);
+      }
+      break;
+    case "promote-action": {
+      if (!op.actionId || typeof op.actionId !== "string") {
+        throw new Error(`${path}: promote-action requires actionId string`);
+      }
+      const validPlacements = ["header", "inline", "context", "assistant"];
+      if (!op.placement || !validPlacements.includes(op.placement)) {
+        throw new Error(`${path}: promote-action placement must be one of ${validPlacements.join(", ")}`);
+      }
+      break;
+    }
+    case "set-focus":
+      if (!op.targetId || typeof op.targetId !== "string") {
+        throw new Error(`${path}: set-focus requires targetId string`);
+      }
+      break;
+    default:
+      throw new Error(`${path}: unknown op "${opType}"`);
+  }
+}
+function validateSurfacePatch(ops) {
+  if (!Array.isArray(ops)) {
+    throw new Error("Patch ops must be an array");
+  }
+  for (let i = 0;i < ops.length; i++) {
+    const op = ops[i];
+    if (op)
+      validateSurfacePatchOp(op, i);
+  }
+}
+function validateSurfaceNodeAgainstKinds(node, allowedKinds, path) {
+  if (!allowedKinds.includes(node.kind)) {
+    throw new Error(`${path}: kind "${node.kind}" not in allowed list [${allowedKinds.join(", ")}]`);
+  }
+  if (node.children) {
+    for (let i = 0;i < node.children.length; i++) {
+      const child = node.children[i];
+      if (child)
+        validateSurfaceNodeAgainstKinds(child, allowedKinds, `${path}.children[${i}]`);
+    }
+  }
+}
+function validatePatchProposal(ops, constraints) {
+  if (!Array.isArray(ops)) {
+    throw new Error("Patch ops must be an array");
+  }
+  const { allowedOps, allowedSlots, allowedNodeKinds } = constraints;
+  for (let i = 0;i < ops.length; i++) {
+    const op = ops[i];
+    if (!op)
+      continue;
+    const path = `ops[${i}]`;
+    if (!allowedOps.includes(op.op)) {
+      throw new Error(`${path}: op "${op.op}" not in allowed list [${allowedOps.join(", ")}]`);
+    }
+    switch (op.op) {
+      case "insert-node":
+        if (!allowedSlots.includes(op.slotId)) {
+          throw new Error(`${path}: slotId "${op.slotId}" not in allowed slots [${allowedSlots.join(", ")}]`);
+        }
+        if (op.node) {
+          validateSurfaceNodeAgainstKinds(op.node, allowedNodeKinds, `${path}.node`);
+        }
+        break;
+      case "move-node":
+        if (!allowedSlots.includes(op.toSlotId)) {
+          throw new Error(`${path}: toSlotId "${op.toSlotId}" not in allowed slots [${allowedSlots.join(", ")}]`);
+        }
+        break;
+      case "replace-node":
+        if (op.node) {
+          validateSurfaceNodeAgainstKinds(op.node, allowedNodeKinds, `${path}.node`);
+        }
+        break;
+      default:
+        break;
+    }
+  }
+  validateSurfacePatch(ops);
+}
+
+// src/runtime/apply-surface-patch.ts
+import { Logger } from "@contractspec/lib.observability";
+var logger = new Logger("@contractspec/lib.surface-runtime");
+function findNode(nodes, nodeId) {
+  for (const n of nodes) {
+    if (n.nodeId === nodeId)
+      return n;
+    if (n.children) {
+      const found = findNode(n.children, nodeId);
+      if (found)
+        return found;
+    }
+  }
+  return;
+}
+function collectNodeIds(nodes) {
+  const ids = new Set;
+  for (const n of nodes) {
+    ids.add(n.nodeId);
+    if (n.children)
+      collectNodeIds(n.children).forEach((id) => ids.add(id));
+  }
+  return ids;
+}
+function validateOp(op, nodeIds) {
+  if (op.op === "remove-node" || op.op === "replace-node" || op.op === "move-node") {
+    if (!nodeIds.has(op.nodeId)) {
+      throw new Error(`Patch op references unknown nodeId: ${op.nodeId}`);
+    }
+  }
+  if (op.op === "insert-node" && !op.node?.nodeId) {
+    throw new Error("insert-node requires node with nodeId");
+  }
+}
+function produceInverse(op, plan) {
+  switch (op.op) {
+    case "insert-node":
+      return op.node ? { op: "remove-node", nodeId: op.node.nodeId } : null;
+    case "remove-node": {
+      const node = findNode(plan.nodes, op.nodeId);
+      return node ? { op: "insert-node", slotId: "primary", node } : null;
+    }
+    case "replace-node": {
+      const prev = findNode(plan.nodes, op.nodeId);
+      return prev ? { op: "replace-node", nodeId: op.nodeId, node: prev } : null;
+    }
+    case "set-layout":
+      return { op: "set-layout", layoutId: plan.layoutId };
+    case "reveal-field":
+      return { op: "hide-field", fieldId: op.fieldId };
+    case "hide-field":
+      return { op: "reveal-field", fieldId: op.fieldId };
+    case "move-node":
+    case "resize-panel":
+    case "set-focus":
+    case "promote-action":
+      return null;
+    default:
+      return null;
+  }
+}
+function applySurfacePatch(plan, ops) {
+  if (ops.length === 0)
+    return { plan, inverseOps: [] };
+  validateSurfacePatch(ops);
+  const nodeIds = collectNodeIds(plan.nodes);
+  for (const op of ops) {
+    validateOp(op, nodeIds);
+  }
+  let nextNodes = [...plan.nodes];
+  let nextLayoutId = plan.layoutId;
+  const inverseOps = [];
+  for (const op of ops) {
+    const inv = produceInverse(op, {
+      ...plan,
+      nodes: nextNodes,
+      layoutId: nextLayoutId
+    });
+    if (inv)
+      inverseOps.unshift(inv);
+    switch (op.op) {
+      case "insert-node":
+        if (op.node)
+          nextNodes = [...nextNodes, op.node];
+        break;
+      case "remove-node":
+        nextNodes = nextNodes.filter((n) => n.nodeId !== op.nodeId);
+        break;
+      case "replace-node": {
+        const replace = (nodes) => nodes.map((n) => n.nodeId === op.nodeId ? op.node : { ...n, children: n.children ? replace(n.children) : undefined });
+        nextNodes = replace(nextNodes);
+        break;
+      }
+      case "set-layout":
+        nextLayoutId = op.layoutId;
+        break;
+      case "move-node":
+      case "resize-panel":
+      case "set-focus":
+      case "reveal-field":
+      case "hide-field":
+      case "promote-action":
+        break;
+    }
+  }
+  const result = {
+    plan: { ...plan, nodes: nextNodes, layoutId: nextLayoutId },
+    inverseOps
+  };
+  logger.info("bundle.surface.patch.applied", {
+    bundleKey: plan.bundleKey,
+    surfaceId: plan.surfaceId,
+    opCount: ops.length,
+    opTypes: [...new Set(ops.map((o) => o.op))]
+  });
+  return result;
+}
+
+// src/runtime/override-store.ts
+function buildOverrideTargetKey(bundleKey, surfaceId, routeId) {
+  return routeId ? `${bundleKey}:${routeId}:${surfaceId}` : `${bundleKey}:${surfaceId}`;
+}
+function createOverrideStoreWithApprovalGate(store, options) {
+  const { requireApprovalForWorkspacePatches = false, requestApproval } = options;
+  return {
+    list: store.list.bind(store),
+    async save(scope, targetKey, patch, saveOptions) {
+      if (requireApprovalForWorkspacePatches && scope === "workspace" && requestApproval) {
+        const approved = await requestApproval({ scope, targetKey, patch });
+        if (!approved) {
+          throw new Error("Workspace overlay save rejected: approval required and not granted");
+        }
+      }
+      return store.save(scope, targetKey, patch, saveOptions);
+    },
+    remove: store.remove.bind(store)
+  };
+}
+function createInMemoryOverrideStore() {
+  const overrides = new Map;
+  function nextId() {
+    return `ov_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+  return {
+    async list(scope, targetKey) {
+      return Array.from(overrides.values()).filter((o) => o.scope === scope && o.targetKey === targetKey);
+    },
+    async save(scope, targetKey, patch, options) {
+      const overrideId = options?.overrideId ?? nextId();
+      const stored = {
+        overrideId,
+        scope,
+        targetKey,
+        patch,
+        createdAt: new Date().toISOString(),
+        createdBy: options?.createdBy
+      };
+      overrides.set(overrideId, stored);
+      return overrideId;
+    },
+    async remove(overrideId) {
+      overrides.delete(overrideId);
+    }
+  };
+}
+
+// src/runtime/resolve-bundle.ts
+import { traceAsync } from "@contractspec/lib.observability/tracing";
+import { Logger as Logger2 } from "@contractspec/lib.observability";
+var logger2 = new Logger2("@contractspec/lib.surface-runtime");
+function getOpTarget(op) {
+  switch (op.op) {
+    case "hide-field":
+    case "reveal-field":
+      return `field:${op.fieldId}`;
+    case "remove-node":
+    case "replace-node":
+    case "move-node":
+      return `node:${op.nodeId}`;
+    case "insert-node":
+      return op.slotId ? `slot:${op.slotId}` : null;
+    default:
+      return null;
+  }
+}
+function matchRoute(pathPattern, route) {
+  if (pathPattern === route)
+    return true;
+  const patternParts = pathPattern.split("/");
+  const routeParts = route.split("/");
+  if (patternParts.length !== routeParts.length)
+    return false;
+  for (let i = 0;i < patternParts.length; i++) {
+    const p = patternParts[i];
+    const r = routeParts[i];
+    if (p?.startsWith(":"))
+      continue;
+    if (p !== r)
+      return false;
+  }
+  return true;
+}
+function selectSurface(spec, ctx) {
+  const route = spec.routes.find((r) => matchRoute(r.path, ctx.route)) ?? spec.routes[0];
+  if (!route) {
+    throw new Error("No routes declared in bundle spec.");
+  }
+  const fallbackRoute = !spec.routes.find((r) => matchRoute(r.path, ctx.route));
+  let surface = spec.surfaces[route.defaultSurface];
+  let fallback;
+  if (!surface && route.candidateSurfaces?.length) {
+    for (const sid of route.candidateSurfaces) {
+      surface = spec.surfaces[sid];
+      if (surface) {
+        fallback = `surface=${sid}`;
+        break;
+      }
+    }
+  }
+  if (!surface) {
+    const overview = Object.values(spec.surfaces).find((s) => s.kind === "overview");
+    if (overview) {
+      surface = overview;
+      fallback = "surface=overview";
+    }
+  }
+  if (!surface) {
+    throw new Error(`Default surface "${route.defaultSurface}" was not found.`);
+  }
+  return {
+    surface,
+    routeId: route.routeId,
+    fallback: fallback ?? (fallbackRoute ? "route" : undefined)
+  };
+}
+function selectLayout(surface, ctx, spec) {
+  let preferredLayoutId;
+  if (ctx.activeViewId && ctx.entity?.type && spec?.entities?.viewKinds) {
+    const viewKind = spec.entities.viewKinds[ctx.activeViewId];
+    const entityType = spec.entities.entityTypes[ctx.entity.type];
+    if (viewKind?.defaultLayoutId && entityType?.supportedViews?.includes(ctx.activeViewId)) {
+      preferredLayoutId = viewKind.defaultLayoutId;
+    }
+  }
+  const matching = surface.layouts.filter((candidate) => candidate.when?.(ctx) ?? true);
+  let layout;
+  if (preferredLayoutId) {
+    layout = matching.find((l) => l.layoutId === preferredLayoutId) ?? surface.layouts.find((l) => l.layoutId === preferredLayoutId) ?? matching[matching.length - 1] ?? surface.layouts[0];
+  } else {
+    layout = matching[matching.length - 1] ?? surface.layouts[0];
+  }
+  if (!layout) {
+    throw new Error(`Surface "${surface.surfaceId}" has no layouts.`);
+  }
+  const layoutFallback = matching.length === 0 && surface.layouts.length > 0;
+  return { layout, layoutFallback: layoutFallback || undefined };
+}
+function resolveDataRecipes(recipes, ctx) {
+  const bindings = {};
+  for (const r of recipes) {
+    if (r.when?.(ctx) ?? true) {
+      const key = r.hydrateInto ?? r.recipeId;
+      bindings[key] = { recipeId: r.recipeId, source: r.source, _stub: true };
+    }
+  }
+  return bindings;
+}
+function allowFromDecision(decision) {
+  if (!decision)
+    return true;
+  return decision.effect === "allow" || decision.effect === "allow-session-only";
+}
+function generateResolutionId() {
+  return `res_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+var OVERLAY_SCOPE_ORDER = [
+  "system",
+  "workspace",
+  "team",
+  "user",
+  "session"
+];
+function buildAdaptation(ctx) {
+  const profile = resolvePreferenceProfile(ctx);
+  const notes = [...profile.notes];
+  const constrainedEntries = Object.entries(profile.constrained);
+  if (constrainedEntries.length > 0) {
+    notes.push(`constrained: ${constrainedEntries.map(([k, v]) => `${k}=${v}`).join(", ")}`);
+  }
+  return {
+    appliedDimensions: profile.canonical,
+    notes
+  };
+}
+async function resolveBundle(spec, ctx, options) {
+  return traceAsync("surface.resolveBundle", async (span) => {
+    const start = performance.now();
+    try {
+      const plan = await resolveBundleInternal(spec, ctx, options);
+      const durationMs = performance.now() - start;
+      resolutionDurationMs.record(durationMs, {
+        bundleKey: spec.meta.key,
+        surfaceId: plan.surfaceId,
+        fallback: plan.surfaceId === "_error" ? "error" : plan.audit.reasons.some((r) => r.startsWith("fallback=")) ? "yes" : "no"
+      });
+      span.setAttribute("bundle.key", spec.meta.key);
+      span.setAttribute("surface.id", plan.surfaceId);
+      span.setAttribute("resolution.duration_ms", durationMs);
+      logger2.info("bundle.surface.resolved", {
+        bundleKey: spec.meta.key,
+        surfaceId: plan.surfaceId,
+        layoutId: plan.layoutId,
+        resolutionMs: Math.round(durationMs),
+        fallback: plan.audit.reasons.some((r) => r.startsWith("fallback=")),
+        nodeCount: plan.nodes.length
+      });
+      return plan;
+    } catch (err) {
+      const durationMs = performance.now() - start;
+      resolutionDurationMs.record(durationMs, {
+        bundleKey: spec.meta.key,
+        surfaceId: "_error",
+        fallback: "error"
+      });
+      return createErrorPlan(spec, ctx, err);
+    }
+  }, "@contractspec/lib.surface-runtime");
+}
+async function resolveBundleInternal(spec, ctx, options) {
+  const {
+    surface,
+    routeId,
+    fallback: surfaceFallback
+  } = selectSurface(spec, ctx);
+  const { layout, layoutFallback } = selectLayout(surface, ctx, spec);
+  let bindings = resolveDataRecipes(surface.data, ctx);
+  const redactBinding = options?.policy?.redactBinding;
+  if (redactBinding) {
+    const redacted = {};
+    for (const [k, v] of Object.entries(bindings)) {
+      redacted[k] = redactBinding(k, ctx) ?? v;
+    }
+    bindings = redacted;
+  }
+  let nodes = [];
+  const evaluateNode = options?.policy?.evaluateNode;
+  if (evaluateNode) {
+    nodes = nodes.filter((n) => allowFromDecision(evaluateNode(n, ctx)));
+  }
+  const reasons = [
+    `surface=${surface.surfaceId}`,
+    `layout=${layout.layoutId}`,
+    `density=${ctx.preferences.density}`,
+    `narrative=${ctx.preferences.narrative}`
+  ];
+  if (surfaceFallback) {
+    reasons.push(`fallback=${surfaceFallback}`);
+    surfaceFallbackCounter.add(1, {
+      bundleKey: spec.meta.key,
+      type: "surface"
+    });
+  }
+  if (layoutFallback) {
+    reasons.push("fallback=layout");
+    surfaceFallbackCounter.add(1, { bundleKey: spec.meta.key, type: "layout" });
+  }
+  const resolutionId = generateResolutionId();
+  const plan = {
+    bundleKey: spec.meta.key,
+    surfaceId: surface.surfaceId,
+    layoutId: layout.layoutId,
+    layoutRoot: layout.root,
+    nodes,
+    actions: surface.actions ?? [],
+    commands: surface.commands ?? [],
+    bindings,
+    adaptation: buildAdaptation(ctx),
+    overlays: [],
+    ai: {
+      plannerId: spec.ai?.plannerId
+    },
+    audit: {
+      resolutionId,
+      createdAt: new Date().toISOString(),
+      reasons
+    },
+    locale: ctx.locale
+  };
+  options?.audit?.emit({
+    eventId: `evt_${resolutionId}`,
+    at: new Date().toISOString(),
+    actorId: ctx.actorId,
+    source: "system",
+    bundleKey: spec.meta.key,
+    surfaceId: surface.surfaceId,
+    eventType: "surface.resolved",
+    payload: {
+      resolutionId,
+      layoutId: layout.layoutId,
+      reasons,
+      nodeCount: nodes.length
+    }
+  });
+  let finalPlan = plan;
+  if (options?.overlayMerge) {
+    const { overrideStore, scopes = OVERLAY_SCOPE_ORDER } = options.overlayMerge;
+    const targetKey = buildOverrideTargetKey(spec.meta.key, surface.surfaceId, routeId);
+    const appliedOverlays = [];
+    const conflicts = [];
+    const seenTargets = new Map;
+    const conflictKeys = new Set;
+    for (const scope of scopes) {
+      if (scope === "session")
+        continue;
+      const stored = await overrideStore.list(scope, targetKey);
+      for (const ov of stored) {
+        if (ov.patch.length === 0)
+          continue;
+        for (const op of ov.patch) {
+          const opTarget = getOpTarget(op);
+          if (opTarget) {
+            const prev = seenTargets.get(opTarget);
+            if (prev && prev.scope !== scope) {
+              const ck = [opTarget, prev.scope, scope].sort().join(":");
+              if (!conflictKeys.has(ck)) {
+                conflictKeys.add(ck);
+                conflicts.push({
+                  targetKey: opTarget,
+                  scopeA: prev.scope,
+                  scopeB: scope,
+                  overlayIdA: prev.overlayId,
+                  overlayIdB: ov.overrideId
+                });
+              }
+            }
+            seenTargets.set(opTarget, { scope, overlayId: ov.overrideId });
+          }
+        }
+        try {
+          const { plan: next } = applySurfacePatch(finalPlan, ov.patch);
+          finalPlan = next;
+          appliedOverlays.push({
+            overlayId: ov.overrideId,
+            scope,
+            appliedOps: ov.patch.length
+          });
+        } catch (err) {
+          logger2.warn("bundle.overlay.apply.failed", {
+            overlayId: ov.overrideId,
+            scope,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    }
+    finalPlan = {
+      ...finalPlan,
+      overlays: appliedOverlays,
+      overlayConflicts: conflicts.length > 0 ? conflicts : undefined
+    };
+  }
+  return finalPlan;
+}
+function createErrorPlan(spec, ctx, err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const errorLayoutRoot = {
+    type: "stack",
+    direction: "vertical",
+    children: [{ type: "slot", slotId: "primary" }]
+  };
+  return {
+    bundleKey: spec.meta.key,
+    surfaceId: "_error",
+    layoutId: "_error",
+    layoutRoot: errorLayoutRoot,
+    nodes: [],
+    actions: [],
+    commands: [],
+    bindings: {},
+    adaptation: {
+      appliedDimensions: ctx.preferences,
+      notes: [`resolution failed: ${message}`]
+    },
+    overlays: [],
+    ai: {},
+    audit: {
+      resolutionId: generateResolutionId(),
+      createdAt: new Date().toISOString(),
+      reasons: ["fallback=error", `error=${message}`]
+    },
+    locale: ctx.locale
+  };
+}
+
+// src/runtime/build-context.ts
+var DEFAULT_PREFERENCES = {
+  guidance: "hints",
+  density: "standard",
+  dataDepth: "detailed",
+  control: "standard",
+  media: "text",
+  pace: "balanced",
+  narrative: "top-down"
+};
+function buildContext(params) {
+  const {
+    route,
+    params: routeParams = {},
+    query = {},
+    tenantId = "default",
+    workspaceId,
+    actorId,
+    device = "desktop",
+    preferences: partialPrefs = {},
+    capabilities = [],
+    featureFlags = [],
+    mode,
+    locale,
+    timezone,
+    entity,
+    conversation,
+    activeViewId
+  } = params;
+  const preferences = {
+    ...DEFAULT_PREFERENCES,
+    ...partialPrefs
+  };
+  return {
+    tenantId,
+    workspaceId,
+    actorId,
+    route,
+    params: routeParams,
+    query,
+    device,
+    mode,
+    locale,
+    timezone,
+    entity,
+    conversation,
+    activeViewId,
+    preferences,
+    capabilities,
+    featureFlags
+  };
+}
+
+// src/evals/golden-harness.ts
+function toSnapshotPlan(plan) {
+  return {
+    bundleKey: plan.bundleKey,
+    surfaceId: plan.surfaceId,
+    layoutId: plan.layoutId,
+    layoutRoot: plan.layoutRoot,
+    nodeCount: plan.nodes.length,
+    actionCount: plan.actions.length,
+    commandCount: plan.commands.length,
+    bindingKeys: Object.keys(plan.bindings).sort(),
+    reasons: [...plan.audit.reasons].sort(),
+    fallback: plan.audit.reasons.some((r) => r.startsWith("fallback="))
+  };
+}
+async function runGoldenResolve(spec, ctx) {
+  const fullCtx = buildContext({
+    route: ctx.route,
+    params: ctx.params ?? {},
+    device: ctx.device ?? "desktop",
+    preferences: ctx.preferences,
+    capabilities: ctx.capabilities ?? []
+  });
+  const plan = await resolveBundle(spec, fullCtx);
+  return toSnapshotPlan(plan);
+}
+export {
+  toSnapshotPlan,
+  runGoldenResolve
+};