@contractspec/lib.surface-runtime 0.2.0

package/dist/runtime/resolve-bundle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/resolve-preferences.d.ts

@@ -0,0 +1,9 @@
+import type { BundleContext, ResolvedPreferenceProfile } from '../spec/types';
+/**
+ * Resolves preferences by scope order (user → workspace-user → bundle → surface → entity → session)
+ * and applies constraint resolution stub.
+ *
+ * @param ctx - Bundle context with preferences
+ * @returns Resolved preference profile with canonical values and source attribution
+ */
+export declare function resolvePreferenceProfile<C extends BundleContext>(ctx: C): ResolvedPreferenceProfile;

package/dist/runtime/resolve-preferences.js

@@ -0,0 +1,60 @@
+// @bun
+// 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
+  };
+}
+export {
+  resolvePreferenceProfile
+};

package/dist/runtime/resolve-preferences.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/rollback.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Rollback API for surface patches.
+ * Reverts last N approved patches by applying their inverse ops.
+ */
+import type { ResolvedSurfacePlan } from './resolve-bundle';
+import type { OverlayApprovalMeta } from '../spec/types';
+export interface RollbackResult {
+    plan: ResolvedSurfacePlan;
+    revertedCount: number;
+    remainingStack: OverlayApprovalMeta[];
+}
+/**
+ * Reverts the last N approved patches by applying their inverse ops in order.
+ * Each OverlayApprovalMeta must have inverseOps; forward ops are ignored.
+ *
+ * @param plan - Current resolved plan (after patches were applied)
+ * @param approvalStack - Stack of approval metadata (most recent last)
+ * @param count - Number of patches to revert (default 1)
+ * @returns Updated plan, reverted count, and remaining stack
+ */
+export declare function rollbackSurfacePatches(plan: ResolvedSurfacePlan, approvalStack: OverlayApprovalMeta[], count?: number): RollbackResult;

package/dist/runtime/rollback.js

@@ -0,0 +1,348 @@
+// @bun
+// 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/rollback.ts
+function rollbackSurfacePatches(plan, approvalStack, count = 1) {
+  if (count <= 0 || approvalStack.length === 0) {
+    return { plan, revertedCount: 0, remainingStack: approvalStack };
+  }
+  const toRevert = approvalStack.slice(-count);
+  const remaining = approvalStack.slice(0, -count);
+  const currentPlan = plan;
+  const allInverseOps = [];
+  for (const meta of toRevert) {
+    if (meta.inverseOps.length > 0) {
+      allInverseOps.push(...meta.inverseOps);
+    }
+  }
+  if (allInverseOps.length === 0) {
+    return { plan, revertedCount: 0, remainingStack: approvalStack };
+  }
+  const result = applySurfacePatch(currentPlan, allInverseOps);
+  return {
+    plan: result.plan,
+    revertedCount: toRevert.length,
+    remainingStack: remaining
+  };
+}
+export {
+  rollbackSurfacePatches
+};

package/dist/runtime/rollback.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/widget-registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Widget registry for surface runtime.
+ * Aligns with 09_extension_and_override_model.md.
+ *
+ * Widgets are registered in code, never from AI prompts.
+ * Trust tiers: core | workspace | signed-plugin (never ephemeral-ai).
+ */
+export type WidgetTrust = 'core' | 'workspace' | 'signed-plugin';
+export interface WidgetRegistryEntry {
+    widgetKey: string;
+    title: string;
+    nodeKind: 'custom-widget';
+    render: string;
+    configure?: string;
+    trust: WidgetTrust;
+    requiresCapabilities?: string[];
+    supportedSlots?: string[];
+}
+export interface WidgetRegistry {
+    register(entry: WidgetRegistryEntry): void;
+    get(widgetKey: string): WidgetRegistryEntry | undefined;
+    has(widgetKey: string): boolean;
+    list(): WidgetRegistryEntry[];
+    listByTrust(trust: WidgetTrust): WidgetRegistryEntry[];
+}
+export declare function createWidgetRegistry(): WidgetRegistry;

package/dist/runtime/widget-registry.js

@@ -0,0 +1,37 @@
+// @bun
+// src/runtime/widget-registry.ts
+function validateTrust(trust) {
+  if (trust === "ephemeral-ai") {
+    throw new Error("Widgets cannot be registered with ephemeral-ai trust. Registration is a code/package concern.");
+  }
+  if (trust !== "core" && trust !== "workspace" && trust !== "signed-plugin") {
+    throw new Error(`Invalid widget trust: ${trust}`);
+  }
+}
+function createWidgetRegistry() {
+  const entries = new Map;
+  return {
+    register(entry) {
+      validateTrust(entry.trust);
+      if (entry.nodeKind !== "custom-widget") {
+        throw new Error(`Widget "${entry.widgetKey}" must have nodeKind "custom-widget"`);
+      }
+      entries.set(entry.widgetKey, entry);
+    },
+    get(widgetKey) {
+      return entries.get(widgetKey);
+    },
+    has(widgetKey) {
+      return entries.has(widgetKey);
+    },
+    list() {
+      return Array.from(entries.values());
+    },
+    listByTrust(trust) {
+      return Array.from(entries.values()).filter((e) => e.trust === trust);
+    }
+  };
+}
+export {
+  createWidgetRegistry
+};

package/dist/runtime/widget-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spec/define-module-bundle.d.ts

@@ -0,0 +1,17 @@
+import type { ModuleBundleSpec } from './types';
+/**
+ * Defines a module bundle spec. Validates shape at runtime and returns the spec.
+ *
+ * @param spec - The bundle spec to define
+ * @returns The same spec (for type inference)
+ *
+ * @example
+ * ```ts
+ * const PmWorkbenchBundle = defineModuleBundle({
+ *   meta: { key: "pm.workbench", version: "0.1.0", title: "PM Workbench" },
+ *   routes: [...],
+ *   surfaces: {...},
+ * });
+ * ```
+ */
+export declare function defineModuleBundle<const T extends ModuleBundleSpec>(spec: T): T;

package/dist/spec/define-module-bundle.js

@@ -0,0 +1,114 @@
+// @bun
+// 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 {
+  defineModuleBundle
+};

package/dist/spec/define-module-bundle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spec/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export { defineModuleBundle } from './define-module-bundle';
+export type { VerificationSnapshotInput, VerificationSnapshotSummary, } from './verification-snapshot-types';
+export { validateLayoutSlots, validateBundleNodeKinds, type ValidateNodeKindsResult, } from './validate-bundle';
+export { validateSurfacePatch, validateSurfacePatchOp, validatePatchProposal, type PatchProposalConstraints, } from './validate-surface-patch';