@contractspec/lib.surface-runtime 0.2.0

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

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

package/dist/spec/validate-surface-patch.test.d.ts

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

package/dist/spec/verification-snapshot-types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Types for verification snapshots (14_verification_matrix.md).
+ * Captures surface + preference combination for regression coverage.
+ */
+import type { PreferenceDimensions } from './types';
+/** Input for a verification snapshot: preferences + human-readable label. */
+export interface VerificationSnapshotInput {
+    /** Short label for the snapshot (e.g. "density=minimal"). */
+    label: string;
+    /** Preference overrides for this snapshot. */
+    preferences: Partial<PreferenceDimensions>;
+    /** Optional description of what this combination tests. */
+    description?: string;
+}
+/** Minimal serializable summary of a resolved plan for snapshot comparison. */
+export interface VerificationSnapshotSummary {
+    bundleKey: string;
+    surfaceId: string;
+    layoutId: string;
+    layoutRootType: string;
+    preferences: PreferenceDimensions;
+    slotCount: number;
+}

package/dist/spec/verification-snapshot-types.js

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

package/dist/spec/verification-snapshot.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Verification snapshot coverage for pilot surfaces (14_verification_matrix.md).
+ * Snapshots issue-workbench at key preference points: density, guidance, narrative.
+ */
+export {};

package/dist/telemetry/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Surface runtime telemetry: tracing, metrics, structured logging.
+ * No PII in logs or metric attributes.
+ */
+export { resolutionDurationMs, patchAcceptanceCounter, patchRejectionCounter, policyDenialCounter, surfaceFallbackCounter, missingRendererCounter, } from './surface-metrics';

package/dist/telemetry/index.js

@@ -0,0 +1,21 @@
+// @bun
+// 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/telemetry/surface-metrics.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Surface runtime metrics for resolution, patch acceptance, and policy events.
+ * Integrates with @contractspec/lib.observability.
+ * No PII in metric attributes.
+ */
+/** Resolution duration in milliseconds. */
+export declare const resolutionDurationMs: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/** Patch acceptance counter (approved). Incremented when user accepts AI patch. */
+export declare const patchAcceptanceCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Patch rejection counter. Incremented when user rejects AI patch. */
+export declare const patchRejectionCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Policy denial counter. Incremented when policy denies an action. */
+export declare const policyDenialCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Surface fallback counter. Incremented when resolver uses fallback surface/layout. */
+export declare const surfaceFallbackCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Missing renderer counter. Incremented when slot has no renderer for a node. */
+export declare const missingRendererCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;

package/dist/telemetry/surface-metrics.js

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