@contractspec/lib.surface-runtime 0.2.0

package/dist/runtime/apply-surface-patch.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedSurfacePlan } from './resolve-bundle';
+import type { SurfacePatchOp } from '../spec/types';
+export interface ApplySurfacePatchResult {
+    plan: ResolvedSurfacePlan;
+    inverseOps: SurfacePatchOp[];
+}
+/**
+ * Applies surface patch operations to a resolved plan.
+ * Returns a new plan and inverse ops for undo; does not mutate the input.
+ *
+ * @param plan - The current resolved surface plan
+ * @param ops - Patch operations to apply
+ * @returns Updated plan and inverse ops for undo
+ */
+export declare function applySurfacePatch(plan: ResolvedSurfacePlan, ops: SurfacePatchOp[]): ApplySurfacePatchResult;

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

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

package/dist/runtime/apply-surface-patch.test.d.ts

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

package/dist/runtime/audit-events.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Audit event helpers for surface runtime.
+ * Emit patch/overlay/policy events. Integrate with lib.observability or custom backend.
+ */
+import type { BundleAuditEmitter, SurfacePatchProposal } from '../spec/types';
+/** Emit patch.proposed when AI or workspace proposes patches. */
+export declare function emitPatchProposed(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    proposal: SurfacePatchProposal;
+    actorId?: string;
+}): void;
+/** Emit patch.approved when user accepts a proposal. */
+export declare function emitPatchApproved(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    proposalId: string;
+    source: SurfacePatchProposal['source'];
+    opsCount: number;
+    actorId?: string;
+    reason?: string;
+}): void;
+/** Emit patch.rejected when user rejects a proposal. */
+export declare function emitPatchRejected(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    proposalId: string;
+    source: SurfacePatchProposal['source'];
+    opsCount: number;
+    actorId?: string;
+    reason?: string;
+}): void;
+/** Emit overlay.saved when overlay is persisted. */
+export declare function emitOverlaySaved(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    overlayId: string;
+    scope: string;
+    opsCount: number;
+    actorId?: string;
+}): void;
+/** Emit overlay.applied when overlay is applied at runtime. */
+export declare function emitOverlayApplied(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    overlayId: string;
+    opsCount: number;
+}): void;
+/** Emit overlay.failed when overlay application fails. */
+export declare function emitOverlayFailed(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    overlayId: string;
+    error: string;
+}): void;
+/** Emit policy.denied when policy blocks an action. */
+export declare function emitPolicyDenied(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    targetId: string;
+    reason?: string;
+    actorId?: string;
+}): void;
+/** Emit policy.redacted when policy redacts content. */
+export declare function emitPolicyRedacted(audit: BundleAuditEmitter, args: {
+    bundleKey: string;
+    surfaceId?: string;
+    targetId: string;
+    redactions?: string[];
+    actorId?: string;
+}): void;

package/dist/runtime/audit-events.js

@@ -0,0 +1,138 @@
+// @bun
+// 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/runtime/audit-events.test.d.ts

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

package/dist/runtime/build-context.d.ts

@@ -0,0 +1,9 @@
+import type { BundleContext, BuildContextParams } from '../spec/types';
+/**
+ * Builds a full BundleContext from minimal request params.
+ * Missing fields use sensible defaults for resolution.
+ *
+ * @param params - Minimal request params (route required)
+ * @returns Full BundleContext
+ */
+export declare function buildContext(params: BuildContextParams): BundleContext;

package/dist/runtime/build-context.js

@@ -0,0 +1,56 @@
+// @bun
+// 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/runtime/extension-registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Action and command registries for surface runtime.
+ * Aligns with 09_extension_and_override_model.md.
+ *
+ * BundleExtensionRegistry: registerWidget, registerFieldRenderer, registerAction, registerCommand.
+ */
+import type { ActionSpec, CommandSpec } from '../spec/types';
+import type { WidgetRegistryEntry } from './widget-registry';
+import type { FieldRendererSpec } from '../spec/types';
+import type { MutableFieldRendererRegistry } from './field-renderer-registry';
+export interface BundleExtensionRegistry {
+    registerWidget(entry: WidgetRegistryEntry): void;
+    registerFieldRenderer(kind: string, entry: FieldRendererSpec): void;
+    registerAction(entry: ActionSpec): void;
+    registerCommand(entry: CommandSpec): void;
+}
+export interface ActionRegistry {
+    register(entry: ActionSpec): void;
+    get(actionId: string): ActionSpec | undefined;
+    has(actionId: string): boolean;
+    list(): ActionSpec[];
+}
+export interface CommandRegistry {
+    register(entry: CommandSpec): void;
+    get(commandId: string): CommandSpec | undefined;
+    has(commandId: string): boolean;
+    list(): CommandSpec[];
+}
+export declare function createActionRegistry(): ActionRegistry;
+export declare function createCommandRegistry(): CommandRegistry;
+export interface CreateBundleExtensionRegistryOptions {
+    widgetRegistry: {
+        register(entry: WidgetRegistryEntry): void;
+    };
+    fieldRendererRegistry: MutableFieldRendererRegistry;
+    actionRegistry?: ActionRegistry;
+    commandRegistry?: CommandRegistry;
+}
+export declare function createBundleExtensionRegistry(options: CreateBundleExtensionRegistryOptions): BundleExtensionRegistry;