@contractspec/lib.surface-runtime 0.2.0

package/dist/browser/spec/index.js

@@ -0,0 +1,319 @@
+// 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/spec/validate-bundle.ts
+var KNOWN_NODE_KIND_RENDERERS = new Set([
+  "entity-section",
+  "entity-field",
+  "action-bar",
+  "table",
+  "timeline",
+  "rich-doc",
+  "chat-thread",
+  "assistant-panel",
+  "entity-card",
+  "entity-header",
+  "entity-summary",
+  "entity-activity",
+  "entity-relations",
+  "relation-graph",
+  "custom-widget"
+]);
+function collectSlotIdsFromRegion(node) {
+  const ids = [];
+  if (node.type === "slot") {
+    ids.push(node.slotId);
+  }
+  if (node.type === "panel-group" || node.type === "stack") {
+    for (const child of node.children) {
+      ids.push(...collectSlotIdsFromRegion(child));
+    }
+  }
+  if (node.type === "tabs") {
+    for (const tab of node.tabs) {
+      ids.push(...collectSlotIdsFromRegion(tab.child));
+    }
+  }
+  if (node.type === "floating") {
+    ids.push(node.anchorSlotId);
+    ids.push(...collectSlotIdsFromRegion(node.child));
+  }
+  return ids;
+}
+function validateLayoutSlots(surface) {
+  const declaredSlotIds = new Set(surface.slots.map((s) => s.slotId));
+  for (const layout of surface.layouts) {
+    const layoutSlotIds = collectSlotIdsFromRegion(layout.root);
+    for (const slotId of layoutSlotIds) {
+      if (!declaredSlotIds.has(slotId)) {
+        throw new Error(`Surface "${surface.surfaceId}" layout "${layout.layoutId}" references undeclared slot "${slotId}". Declared slots: ${[...declaredSlotIds].join(", ")}`);
+      }
+    }
+  }
+}
+function validateBundleNodeKinds(surface) {
+  const warnings = [];
+  for (const slot of surface.slots) {
+    for (const kind of slot.accepts) {
+      if (!KNOWN_NODE_KIND_RENDERERS.has(kind)) {
+        warnings.push(`Surface "${surface.surfaceId}" slot "${slot.slotId}" accepts "${kind}" which has no dedicated renderer (generic fallback used)`);
+      }
+    }
+  }
+  return { warnings };
+}
+
+// src/spec/define-module-bundle.ts
+function defineModuleBundle(spec) {
+  if (!spec.meta?.key || !spec.meta?.version || !spec.meta?.title) {
+    throw new Error("ModuleBundleSpec must have meta.key, meta.version, and meta.title");
+  }
+  if (!spec.routes?.length) {
+    throw new Error("ModuleBundleSpec must have at least one route");
+  }
+  if (!spec.surfaces || Object.keys(spec.surfaces).length === 0) {
+    throw new Error("ModuleBundleSpec must have at least one surface");
+  }
+  if (spec.entities) {
+    if (!spec.entities.entityTypes || typeof spec.entities.entityTypes !== "object") {
+      throw new Error("ModuleBundleSpec.entities must have entityTypes object when present");
+    }
+    if (!spec.entities.fieldKinds || typeof spec.entities.fieldKinds !== "object") {
+      throw new Error("ModuleBundleSpec.entities must have fieldKinds object when present");
+    }
+  }
+  const REQUIRED_DIMENSIONS = [
+    "guidance",
+    "density",
+    "dataDepth",
+    "control",
+    "media",
+    "pace",
+    "narrative"
+  ];
+  const MIN_DESCRIPTION_LENGTH = 10;
+  for (const surface of Object.values(spec.surfaces)) {
+    if (!surface.verification?.dimensions) {
+      throw new Error(`Surface "${surface.surfaceId}" must have verification.dimensions for all 7 preference dimensions`);
+    }
+    const dims = surface.verification.dimensions;
+    for (const d of REQUIRED_DIMENSIONS) {
+      const val = dims[d];
+      if (!val || typeof val !== "string") {
+        throw new Error(`Surface "${surface.surfaceId}" verification.dimensions.${d} must be a non-empty string`);
+      }
+      const trimmed = val.trim();
+      if (trimmed.length < MIN_DESCRIPTION_LENGTH) {
+        throw new Error(`Surface "${surface.surfaceId}" verification.dimensions.${d} must be at least ${MIN_DESCRIPTION_LENGTH} characters (got ${trimmed.length})`);
+      }
+    }
+    validateLayoutSlots(surface);
+  }
+  return spec;
+}
+export {
+  validateSurfacePatchOp,
+  validateSurfacePatch,
+  validatePatchProposal,
+  validateLayoutSlots,
+  validateBundleNodeKinds,
+  defineModuleBundle
+};

package/dist/browser/spec/validate-bundle.js

@@ -0,0 +1,65 @@
+// src/spec/validate-bundle.ts
+var KNOWN_NODE_KIND_RENDERERS = new Set([
+  "entity-section",
+  "entity-field",
+  "action-bar",
+  "table",
+  "timeline",
+  "rich-doc",
+  "chat-thread",
+  "assistant-panel",
+  "entity-card",
+  "entity-header",
+  "entity-summary",
+  "entity-activity",
+  "entity-relations",
+  "relation-graph",
+  "custom-widget"
+]);
+function collectSlotIdsFromRegion(node) {
+  const ids = [];
+  if (node.type === "slot") {
+    ids.push(node.slotId);
+  }
+  if (node.type === "panel-group" || node.type === "stack") {
+    for (const child of node.children) {
+      ids.push(...collectSlotIdsFromRegion(child));
+    }
+  }
+  if (node.type === "tabs") {
+    for (const tab of node.tabs) {
+      ids.push(...collectSlotIdsFromRegion(tab.child));
+    }
+  }
+  if (node.type === "floating") {
+    ids.push(node.anchorSlotId);
+    ids.push(...collectSlotIdsFromRegion(node.child));
+  }
+  return ids;
+}
+function validateLayoutSlots(surface) {
+  const declaredSlotIds = new Set(surface.slots.map((s) => s.slotId));
+  for (const layout of surface.layouts) {
+    const layoutSlotIds = collectSlotIdsFromRegion(layout.root);
+    for (const slotId of layoutSlotIds) {
+      if (!declaredSlotIds.has(slotId)) {
+        throw new Error(`Surface "${surface.surfaceId}" layout "${layout.layoutId}" references undeclared slot "${slotId}". Declared slots: ${[...declaredSlotIds].join(", ")}`);
+      }
+    }
+  }
+}
+function validateBundleNodeKinds(surface) {
+  const warnings = [];
+  for (const slot of surface.slots) {
+    for (const kind of slot.accepts) {
+      if (!KNOWN_NODE_KIND_RENDERERS.has(kind)) {
+        warnings.push(`Surface "${surface.surfaceId}" slot "${slot.slotId}" accepts "${kind}" which has no dedicated renderer (generic fallback used)`);
+      }
+    }
+  }
+  return { warnings };
+}
+export {
+  validateLayoutSlots,
+  validateBundleNodeKinds
+};

package/dist/browser/spec/validate-surface-patch.js

@@ -0,0 +1,206 @@
+// 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);
+}
+export {
+  validateSurfacePatchOp,
+  validateSurfacePatch,
+  validatePatchProposal
+};

package/dist/browser/telemetry/index.js

@@ -0,0 +1,20 @@
+// 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);
+export {
+  surfaceFallbackCounter,
+  resolutionDurationMs,
+  policyDenialCounter,
+  patchRejectionCounter,
+  patchAcceptanceCounter,
+  missingRendererCounter
+};

package/dist/browser/telemetry/surface-metrics.js

@@ -0,0 +1,20 @@
+// 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);
+export {
+  surfaceFallbackCounter,
+  resolutionDurationMs,
+  policyDenialCounter,
+  patchRejectionCounter,
+  patchAcceptanceCounter,
+  missingRendererCounter
+};

package/dist/evals/golden-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Golden context format for resolver evals.
+ * Fixed bundle context plus expected output constraints.
+ * No PII.
+ */
+import type { PreferenceDimensions } from '../spec/types';
+export interface GoldenContext {
+    /** Route path (e.g. /operate/pm/issues/:issueId). */
+    route: string;
+    /** Route params (e.g. { issueId: '123' }). */
+    params?: Record<string, string>;
+    /** Partial preferences; rest use defaults. */
+    preferences?: Partial<PreferenceDimensions>;
+    /** Device type. */
+    device?: 'desktop' | 'tablet' | 'mobile';
+    /** Capability flags. */
+    capabilities?: string[];
+    /** Optional description for the golden case. */
+    description?: string;
+}
+export interface GoldenContextFile {
+    version: 1;
+    contexts: GoldenContext[];
+}

package/dist/evals/golden-context.js

@@ -0,0 +1 @@
+// @bun

package/dist/evals/golden-harness.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Golden-context harness for resolver evals.
+ * Runs resolver with golden contexts and snapshots ResolvedSurfacePlan.
+ */
+import type { ModuleBundleSpec } from '../spec/types';
+import type { BundleContext } from '../spec/types';
+import type { ResolvedSurfacePlan } from '../runtime/resolve-bundle';
+import type { GoldenContext } from './golden-context';
+/** Snapshot-friendly plan (deterministic fields only). */
+export interface SnapshotPlan {
+    bundleKey: string;
+    surfaceId: string;
+    layoutId: string;
+    layoutRoot: unknown;
+    nodeCount: number;
+    actionCount: number;
+    commandCount: number;
+    bindingKeys: string[];
+    reasons: string[];
+    fallback: boolean;
+}
+/**
+ * Redacts non-deterministic fields before snapshotting.
+ */
+export declare function toSnapshotPlan(plan: ResolvedSurfacePlan): SnapshotPlan;
+/**
+ * Runs resolver with golden context and returns snapshot plan.
+ */
+export declare function runGoldenResolve<C extends BundleContext>(spec: ModuleBundleSpec<C>, ctx: GoldenContext): Promise<SnapshotPlan>;