@contractspec/lib.surface-runtime 0.2.0

package/dist/evals/golden-harness.test.d.ts

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

package/dist/examples/pm-workbench.bundle.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Example PM workbench bundle. Demonstrates defineModuleBundle usage.
+ * Typechecks against @contractspec/lib.surface-runtime public API.
+ */
+export declare const PmWorkbenchBundle: {
+    readonly meta: {
+        readonly key: "pm.workbench";
+        readonly version: "0.1.0";
+        readonly title: "PM Workbench";
+        readonly description: "AI-native PM workbench for relation-rich issues and saved views";
+        readonly owners: ["team-pm-platform"];
+        readonly tags: ["pm", "issues", "workbench", "ai-native"];
+        readonly stability: "experimental";
+    };
+    readonly routes: [{
+        readonly routeId: "pm-issue";
+        readonly path: "/operate/pm/issues/:issueId";
+        readonly defaultSurface: "issue-workbench";
+    }];
+    readonly entities: {
+        readonly entityTypes: {
+            readonly 'pm.issue': {
+                readonly entityType: "pm.issue";
+                readonly defaultSurfaceId: "issue-workbench";
+                readonly detailBlueprints: ["balanced-three-pane", "dense-ops-mode"];
+                readonly supportedViews: ["minimal-summary", "balanced-detail", "dense-workbench"];
+                readonly sectionsFromSchema: true;
+                readonly fieldsFromSchema: true;
+                readonly relationPanels: ["relations", "meeting-evidence", "decision-trail"];
+            };
+        };
+        readonly fieldKinds: {
+            readonly text: {
+                readonly fieldKind: "text";
+                readonly viewer: "text-viewer";
+                readonly editor: "text-editor";
+            };
+            readonly number: {
+                readonly fieldKind: "number";
+                readonly viewer: "number-viewer";
+                readonly editor: "number-editor";
+            };
+            readonly date: {
+                readonly fieldKind: "date";
+                readonly viewer: "date-viewer";
+                readonly editor: "date-editor";
+            };
+            readonly select: {
+                readonly fieldKind: "select";
+                readonly viewer: "select-viewer";
+                readonly editor: "select-editor";
+            };
+        };
+        readonly sectionKinds: {
+            readonly overview: {
+                readonly sectionKind: "overview";
+                readonly renderer: "section-overview";
+            };
+            readonly details: {
+                readonly sectionKind: "details";
+                readonly renderer: "section-details";
+            };
+            readonly relations: {
+                readonly sectionKind: "relations";
+                readonly renderer: "section-relations";
+            };
+            readonly activity: {
+                readonly sectionKind: "activity";
+                readonly renderer: "section-activity";
+            };
+        };
+        readonly viewKinds: {
+            readonly 'minimal-summary': {
+                readonly viewKind: "minimal-summary";
+                readonly renderer: "view-minimal";
+            };
+            readonly 'balanced-detail': {
+                readonly viewKind: "balanced-detail";
+                readonly renderer: "view-balanced";
+                readonly defaultLayoutId: "balanced-three-pane";
+            };
+            readonly 'dense-workbench': {
+                readonly viewKind: "dense-workbench";
+                readonly renderer: "view-dense";
+                readonly defaultLayoutId: "dense-ops-mode";
+            };
+        };
+    };
+    readonly surfaces: {
+        readonly 'issue-workbench': {
+            readonly surfaceId: "issue-workbench";
+            readonly kind: "workbench";
+            readonly title: "Issue Workbench";
+            readonly slots: [{
+                readonly slotId: "header";
+                readonly role: "header";
+                readonly accepts: ["action-bar"];
+                readonly cardinality: "many";
+            }, {
+                readonly slotId: "primary";
+                readonly role: "primary";
+                readonly accepts: ["entity-section", "table", "rich-doc"];
+                readonly cardinality: "many";
+                readonly mutableByAi: true;
+                readonly mutableByUser: true;
+            }, {
+                readonly slotId: "secondary";
+                readonly role: "secondary";
+                readonly accepts: ["entity-section", "table", "timeline"];
+                readonly cardinality: "many";
+                readonly mutableByAi: true;
+                readonly mutableByUser: true;
+            }, {
+                readonly slotId: "assistant";
+                readonly role: "assistant";
+                readonly accepts: ["assistant-panel", "chat-thread"];
+                readonly cardinality: "many";
+                readonly mutableByAi: true;
+                readonly mutableByUser: true;
+            }, {
+                readonly slotId: "inspector";
+                readonly role: "inspector";
+                readonly accepts: ["entity-field", "relation-graph", "custom-widget"];
+                readonly cardinality: "many";
+                readonly mutableByAi: true;
+                readonly mutableByUser: true;
+            }];
+            readonly layouts: [{
+                readonly layoutId: "balanced-three-pane";
+                readonly title: "Balanced 3-pane";
+                readonly root: {
+                    readonly type: "panel-group";
+                    readonly direction: "horizontal";
+                    readonly persistKey: "pm.issue.balanced-three-pane";
+                    readonly children: [{
+                        readonly type: "slot";
+                        readonly slotId: "primary";
+                    }, {
+                        readonly type: "panel-group";
+                        readonly direction: "vertical";
+                        readonly persistKey: "pm.issue.right-stack";
+                        readonly children: [{
+                            readonly type: "slot";
+                            readonly slotId: "secondary";
+                        }, {
+                            readonly type: "slot";
+                            readonly slotId: "assistant";
+                        }];
+                    }, {
+                        readonly type: "slot";
+                        readonly slotId: "inspector";
+                    }];
+                };
+            }];
+            readonly data: [{
+                readonly recipeId: "issue-core";
+                readonly source: {
+                    readonly kind: "entity";
+                    readonly entityType: "pm.issue";
+                };
+                readonly requestedDepth: "detailed";
+                readonly hydrateInto: "issue";
+            }];
+            readonly verification: {
+                readonly dimensions: {
+                    readonly guidance: "Can reveal walkthrough notes, field help, and AI explanations.";
+                    readonly density: "Can select compact, balanced, or dense multi-pane layouts.";
+                    readonly dataDepth: "Controls issue relation hydration, activity size, and inspector depth.";
+                    readonly control: "Shows advanced commands and raw config tabs only when allowed.";
+                    readonly media: "Supports text-first detail, visual graph, and hybrid assistant modes.";
+                    readonly pace: "Maps to motion tokens and confirmation behavior.";
+                    readonly narrative: "Can order issue summary before or after evidence/activity sections.";
+                };
+            };
+        };
+    };
+};

package/dist/examples/pm-workbench.bundle.js

@@ -0,0 +1,477 @@
+// @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/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;
+}
+// src/examples/pm-workbench.bundle.ts
+var PmWorkbenchBundle = defineModuleBundle({
+  meta: {
+    key: "pm.workbench",
+    version: "0.1.0",
+    title: "PM Workbench",
+    description: "AI-native PM workbench for relation-rich issues and saved views",
+    owners: ["team-pm-platform"],
+    tags: ["pm", "issues", "workbench", "ai-native"],
+    stability: "experimental"
+  },
+  routes: [
+    {
+      routeId: "pm-issue",
+      path: "/operate/pm/issues/:issueId",
+      defaultSurface: "issue-workbench"
+    }
+  ],
+  entities: {
+    entityTypes: {
+      "pm.issue": {
+        entityType: "pm.issue",
+        defaultSurfaceId: "issue-workbench",
+        detailBlueprints: ["balanced-three-pane", "dense-ops-mode"],
+        supportedViews: [
+          "minimal-summary",
+          "balanced-detail",
+          "dense-workbench"
+        ],
+        sectionsFromSchema: true,
+        fieldsFromSchema: true,
+        relationPanels: ["relations", "meeting-evidence", "decision-trail"]
+      }
+    },
+    fieldKinds: {
+      text: { fieldKind: "text", viewer: "text-viewer", editor: "text-editor" },
+      number: {
+        fieldKind: "number",
+        viewer: "number-viewer",
+        editor: "number-editor"
+      },
+      date: { fieldKind: "date", viewer: "date-viewer", editor: "date-editor" },
+      select: {
+        fieldKind: "select",
+        viewer: "select-viewer",
+        editor: "select-editor"
+      }
+    },
+    sectionKinds: {
+      overview: { sectionKind: "overview", renderer: "section-overview" },
+      details: { sectionKind: "details", renderer: "section-details" },
+      relations: { sectionKind: "relations", renderer: "section-relations" },
+      activity: { sectionKind: "activity", renderer: "section-activity" }
+    },
+    viewKinds: {
+      "minimal-summary": {
+        viewKind: "minimal-summary",
+        renderer: "view-minimal"
+      },
+      "balanced-detail": {
+        viewKind: "balanced-detail",
+        renderer: "view-balanced",
+        defaultLayoutId: "balanced-three-pane"
+      },
+      "dense-workbench": {
+        viewKind: "dense-workbench",
+        renderer: "view-dense",
+        defaultLayoutId: "dense-ops-mode"
+      }
+    }
+  },
+  surfaces: {
+    "issue-workbench": {
+      surfaceId: "issue-workbench",
+      kind: "workbench",
+      title: "Issue Workbench",
+      slots: [
+        {
+          slotId: "header",
+          role: "header",
+          accepts: ["action-bar"],
+          cardinality: "many"
+        },
+        {
+          slotId: "primary",
+          role: "primary",
+          accepts: ["entity-section", "table", "rich-doc"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        },
+        {
+          slotId: "secondary",
+          role: "secondary",
+          accepts: ["entity-section", "table", "timeline"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        },
+        {
+          slotId: "assistant",
+          role: "assistant",
+          accepts: ["assistant-panel", "chat-thread"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        },
+        {
+          slotId: "inspector",
+          role: "inspector",
+          accepts: ["entity-field", "relation-graph", "custom-widget"],
+          cardinality: "many",
+          mutableByAi: true,
+          mutableByUser: true
+        }
+      ],
+      layouts: [
+        {
+          layoutId: "balanced-three-pane",
+          title: "Balanced 3-pane",
+          root: {
+            type: "panel-group",
+            direction: "horizontal",
+            persistKey: "pm.issue.balanced-three-pane",
+            children: [
+              { type: "slot", slotId: "primary" },
+              {
+                type: "panel-group",
+                direction: "vertical",
+                persistKey: "pm.issue.right-stack",
+                children: [
+                  { type: "slot", slotId: "secondary" },
+                  { type: "slot", slotId: "assistant" }
+                ]
+              },
+              { type: "slot", slotId: "inspector" }
+            ]
+          }
+        }
+      ],
+      data: [
+        {
+          recipeId: "issue-core",
+          source: { kind: "entity", entityType: "pm.issue" },
+          requestedDepth: "detailed",
+          hydrateInto: "issue"
+        }
+      ],
+      verification: {
+        dimensions: {
+          guidance: "Can reveal walkthrough notes, field help, and AI explanations.",
+          density: "Can select compact, balanced, or dense multi-pane layouts.",
+          dataDepth: "Controls issue relation hydration, activity size, and inspector depth.",
+          control: "Shows advanced commands and raw config tabs only when allowed.",
+          media: "Supports text-first detail, visual graph, and hybrid assistant modes.",
+          pace: "Maps to motion tokens and confirmation behavior.",
+          narrative: "Can order issue summary before or after evidence/activity sections."
+        }
+      }
+    }
+  }
+});
+export {
+  PmWorkbenchBundle
+};

package/dist/i18n/catalogs/en.d.ts

@@ -0,0 +1 @@
+export declare const enMessages: import("@contractspec/lib.contracts-spec/translations").TranslationSpec;