@contractspec/lib.surface-runtime 0.2.0

package/dist/browser/runtime/apply-surface-patch.js

@@ -0,0 +1,322 @@
+// 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;
+}
+export {
+  applySurfacePatch
+};

package/dist/browser/runtime/audit-events.js

@@ -0,0 +1,137 @@
+// src/runtime/audit-events.ts
+function generateEventId() {
+  return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function emitPatchProposed(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    actorId: args.actorId,
+    source: args.proposal.source === "assistant" ? "assistant" : "user",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "patch.proposed",
+    payload: {
+      proposalId: args.proposal.proposalId,
+      source: args.proposal.source,
+      opsCount: args.proposal.ops.length
+    }
+  });
+}
+function emitPatchApproved(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    actorId: args.actorId,
+    source: "user",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "patch.approved",
+    payload: {
+      proposalId: args.proposalId,
+      source: args.source,
+      opsCount: args.opsCount,
+      reason: args.reason
+    }
+  });
+}
+function emitPatchRejected(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    actorId: args.actorId,
+    source: "user",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "patch.rejected",
+    payload: {
+      proposalId: args.proposalId,
+      source: args.source,
+      opsCount: args.opsCount,
+      reason: args.reason
+    }
+  });
+}
+function emitOverlaySaved(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    actorId: args.actorId,
+    source: "user",
+    bundleKey: args.bundleKey,
+    eventType: "overlay.saved",
+    payload: {
+      overlayId: args.overlayId,
+      scope: args.scope,
+      opsCount: args.opsCount
+    }
+  });
+}
+function emitOverlayApplied(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    source: "system",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "overlay.applied",
+    payload: {
+      overlayId: args.overlayId,
+      opsCount: args.opsCount
+    }
+  });
+}
+function emitOverlayFailed(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    source: "system",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "overlay.failed",
+    payload: {
+      overlayId: args.overlayId,
+      error: args.error
+    }
+  });
+}
+function emitPolicyDenied(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    actorId: args.actorId,
+    source: "policy",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "policy.denied",
+    payload: {
+      targetId: args.targetId,
+      reason: args.reason
+    }
+  });
+}
+function emitPolicyRedacted(audit, args) {
+  audit.emit({
+    eventId: generateEventId(),
+    at: new Date().toISOString(),
+    actorId: args.actorId,
+    source: "policy",
+    bundleKey: args.bundleKey,
+    surfaceId: args.surfaceId,
+    eventType: "policy.redacted",
+    payload: {
+      targetId: args.targetId,
+      redactions: args.redactions
+    }
+  });
+}
+export {
+  emitPolicyRedacted,
+  emitPolicyDenied,
+  emitPatchRejected,
+  emitPatchProposed,
+  emitPatchApproved,
+  emitOverlaySaved,
+  emitOverlayFailed,
+  emitOverlayApplied
+};

package/dist/browser/runtime/build-context.js

@@ -0,0 +1,55 @@
+// 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
+  };
+}
+export {
+  buildContext
+};

package/dist/browser/runtime/extension-registry.js

@@ -0,0 +1,58 @@
+// src/runtime/extension-registry.ts
+function createActionRegistry() {
+  const entries = new Map;
+  return {
+    register(entry) {
+      entries.set(entry.actionId, entry);
+    },
+    get(actionId) {
+      return entries.get(actionId);
+    },
+    has(actionId) {
+      return entries.has(actionId);
+    },
+    list() {
+      return Array.from(entries.values());
+    }
+  };
+}
+function createCommandRegistry() {
+  const entries = new Map;
+  return {
+    register(entry) {
+      entries.set(entry.commandId, entry);
+    },
+    get(commandId) {
+      return entries.get(commandId);
+    },
+    has(commandId) {
+      return entries.has(commandId);
+    },
+    list() {
+      return Array.from(entries.values());
+    }
+  };
+}
+function createBundleExtensionRegistry(options) {
+  const actionRegistry = options.actionRegistry ?? createActionRegistry();
+  const commandRegistry = options.commandRegistry ?? createCommandRegistry();
+  return {
+    registerWidget(entry) {
+      options.widgetRegistry.register(entry);
+    },
+    registerFieldRenderer(kind, entry) {
+      options.fieldRendererRegistry.registerFieldRenderer(kind, entry);
+    },
+    registerAction(entry) {
+      actionRegistry.register(entry);
+    },
+    registerCommand(entry) {
+      commandRegistry.register(entry);
+    }
+  };
+}
+export {
+  createCommandRegistry,
+  createBundleExtensionRegistry,
+  createActionRegistry
+};

package/dist/browser/runtime/field-renderer-registry.js

@@ -0,0 +1,145 @@
+// src/runtime/field-renderer-registry.ts
+var FALLBACK_FIELD_KIND = "text";
+var CORE_FIELD_KINDS = {
+  text: {
+    fieldKind: "text",
+    viewer: "text-viewer",
+    editor: "text-editor",
+    summaryViewer: "text-summary",
+    tableCell: "text-cell",
+    filters: ["contains", "equals", "startsWith", "endsWith"],
+    validators: ["required", "maxLength", "regex"]
+  },
+  number: {
+    fieldKind: "number",
+    viewer: "number-viewer",
+    editor: "number-editor",
+    summaryViewer: "number-summary",
+    tableCell: "number-cell",
+    filters: ["equals", "gt", "gte", "lt", "lte", "between"],
+    validators: ["required", "min", "max", "integer"]
+  },
+  date: {
+    fieldKind: "date",
+    viewer: "date-viewer",
+    editor: "date-editor",
+    summaryViewer: "date-summary",
+    tableCell: "date-cell",
+    filters: ["equals", "before", "after", "between"],
+    validators: ["required", "min", "max"]
+  },
+  select: {
+    fieldKind: "select",
+    viewer: "select-viewer",
+    editor: "select-editor",
+    summaryViewer: "select-summary",
+    tableCell: "select-cell",
+    filters: ["equals", "in"],
+    validators: ["required", "oneOf"]
+  },
+  checkbox: {
+    fieldKind: "checkbox",
+    viewer: "checkbox-viewer",
+    editor: "checkbox-editor",
+    summaryViewer: "checkbox-summary",
+    tableCell: "checkbox-cell",
+    filters: ["equals"],
+    validators: ["required"]
+  }
+};
+var STUB_FIELD_KINDS = {
+  relation: {
+    fieldKind: "relation",
+    viewer: "relation-viewer-stub",
+    summaryViewer: "relation-chip-stub",
+    tableCell: "relation-chip-stub"
+  },
+  rollup: {
+    fieldKind: "rollup",
+    viewer: "rollup-viewer-stub",
+    summaryViewer: "rollup-chip-stub",
+    tableCell: "rollup-cell-stub"
+  },
+  formula: {
+    fieldKind: "formula",
+    viewer: "formula-viewer-stub",
+    summaryViewer: "formula-summary-stub",
+    tableCell: "formula-cell-stub"
+  },
+  people: {
+    fieldKind: "people",
+    viewer: "people-viewer-stub",
+    editor: "people-picker-stub",
+    summaryViewer: "people-chip-stub",
+    tableCell: "people-cell-stub"
+  },
+  options: {
+    fieldKind: "options",
+    viewer: "options-viewer-stub",
+    editor: "options-editor-stub",
+    summaryViewer: "options-chip-stub",
+    tableCell: "options-cell-stub"
+  },
+  instance: {
+    fieldKind: "instance",
+    viewer: "instance-viewer-stub",
+    summaryViewer: "instance-chip-stub",
+    tableCell: "instance-cell-stub"
+  },
+  url: {
+    fieldKind: "url",
+    viewer: "url-viewer",
+    editor: "url-editor",
+    summaryViewer: "url-summary",
+    tableCell: "url-cell",
+    validators: ["required", "regex"]
+  }
+};
+function createFieldRendererRegistry() {
+  const all = { ...CORE_FIELD_KINDS, ...STUB_FIELD_KINDS };
+  const fallback = CORE_FIELD_KINDS[FALLBACK_FIELD_KIND];
+  if (!fallback) {
+    throw new Error(`Fallback field kind "${FALLBACK_FIELD_KIND}" not found`);
+  }
+  return {
+    get(kind) {
+      return all[kind];
+    },
+    has(kind) {
+      return kind in all;
+    },
+    getOrFallback(kind) {
+      return all[kind] ?? fallback;
+    }
+  };
+}
+function createMutableFieldRendererRegistry() {
+  const base = { ...CORE_FIELD_KINDS, ...STUB_FIELD_KINDS };
+  const custom = new Map;
+  const fallback = CORE_FIELD_KINDS[FALLBACK_FIELD_KIND];
+  if (!fallback) {
+    throw new Error(`Fallback field kind "${FALLBACK_FIELD_KIND}" not found`);
+  }
+  return {
+    get(kind) {
+      return custom.get(kind) ?? base[kind];
+    },
+    has(kind) {
+      return custom.has(kind) || kind in base;
+    },
+    getOrFallback(kind) {
+      return custom.get(kind) ?? base[kind] ?? fallback;
+    },
+    registerFieldRenderer(kind, entry) {
+      if (entry.fieldKind !== kind) {
+        throw new Error(`Field renderer entry fieldKind "${entry.fieldKind}" must match kind "${kind}"`);
+      }
+      custom.set(kind, entry);
+    }
+  };
+}
+export {
+  createMutableFieldRendererRegistry,
+  createFieldRendererRegistry,
+  FALLBACK_FIELD_KIND
+};