@contractspec/lib.surface-runtime 0.3.0 → 0.3.3

package/dist/browser/runtime/resolve-bundle.js

@@ -1,444 +1,10 @@
-// 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");
+import { Logger } from "@contractspec/lib.observability";
+import { resolutionDurationMs, surfaceFallbackCounter } from "../telemetry";
+import { resolvePreferenceProfile } from "./resolve-preferences";
+import { applySurfacePatch } from "./apply-surface-patch";
+import { buildOverrideTargetKey } from "./override-store";
+const logger = new Logger("@contractspec/lib.surface-runtime");
 function getOpTarget(op) {
   switch (op.op) {
     case "hide-field":
@@ -544,7 +110,7 @@ function allowFromDecision(decision) {
 function generateResolutionId() {
   return `res_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
-var OVERLAY_SCOPE_ORDER = [
+const OVERLAY_SCOPE_ORDER = [
   "system",
   "workspace",
   "team",
@@ -563,7 +129,7 @@ function buildAdaptation(ctx) {
     notes
   };
 }
-async function resolveBundle(spec, ctx, options) {
+export async function resolveBundle(spec, ctx, options) {
   return traceAsync("surface.resolveBundle", async (span) => {
     const start = performance.now();
     try {
@@ -577,7 +143,7 @@ async function resolveBundle(spec, ctx, options) {
       span.setAttribute("bundle.key", spec.meta.key);
       span.setAttribute("surface.id", plan.surfaceId);
       span.setAttribute("resolution.duration_ms", durationMs);
-      logger2.info("bundle.surface.resolved", {
+      logger.info("bundle.surface.resolved", {
         bundleKey: spec.meta.key,
         surfaceId: plan.surfaceId,
         layoutId: plan.layoutId,
@@ -716,7 +282,7 @@ async function resolveBundleInternal(spec, ctx, options) {
             appliedOps: ov.patch.length
           });
         } catch (err) {
-          logger2.warn("bundle.overlay.apply.failed", {
+          logger.warn("bundle.overlay.apply.failed", {
             overlayId: ov.overrideId,
             scope,
             error: err instanceof Error ? err.message : String(err)
@@ -762,6 +328,3 @@ function createErrorPlan(spec, ctx, err) {
     locale: ctx.locale
   };
 }
-export {
-  resolveBundle
-};

package/dist/browser/runtime/resolve-preferences.js

@@ -1,5 +1,4 @@
-// src/runtime/resolve-preferences.ts
-var DIMENSION_KEYS = [
+const DIMENSION_KEYS = [
   "guidance",
   "density",
   "dataDepth",
@@ -8,7 +7,7 @@ var DIMENSION_KEYS = [
   "pace",
   "narrative"
 ];
-var SCOPE_ORDER = [
+const SCOPE_ORDER = [
   "user",
   "workspace-user",
   "bundle",
@@ -41,7 +40,7 @@ function mergeByScope(layers, ctx) {
 function resolveConstraints(_canonical, _ctx) {
   return { constrained: {}, notes: [] };
 }
-function resolvePreferenceProfile(ctx) {
+export function resolvePreferenceProfile(ctx) {
   const layers = {
     session: ctx.preferences
   };
@@ -54,6 +53,3 @@ function resolvePreferenceProfile(ctx) {
     notes
   };
 }
-export {
-  resolvePreferenceProfile
-};