@contractspec/lib.surface-runtime 0.2.0

package/dist/node/runtime/overlay-alignment.js

@@ -0,0 +1,83 @@
+// src/runtime/overlay-alignment.ts
+import { applyOverlayModifications } from "@contractspec/lib.overlay-engine/merger";
+function toOverlayScopeContext(ctx) {
+  return {
+    tenantId: ctx.tenantId,
+    userId: ctx.actorId,
+    device: ctx.device,
+    tags: ctx.featureFlags
+  };
+}
+function toOverlayTargetRef(_ctx, target) {
+  return {
+    presentation: target.surfaceId ?? target.routeId,
+    bundleKey: target.bundleKey,
+    surfaceId: target.surfaceId,
+    routeId: target.routeId,
+    entityType: target.entityType
+  };
+}
+function toOverlayAppliesTo(ctx, target, scope) {
+  const scopeCtx = toOverlayScopeContext(ctx);
+  return {
+    ...scopeCtx,
+    ...target,
+    ...scope === "user" && ctx.actorId ? { userId: ctx.actorId } : {},
+    ...scope === "workspace" && ctx.workspaceId ? { tags: [...scopeCtx.tags ?? [], `workspace:${ctx.workspaceId}`] } : {}
+  };
+}
+function toOverlayRenderableField(field) {
+  return {
+    key: field.fieldId,
+    label: field.title,
+    visible: field.visible,
+    required: field.required,
+    order: 0
+  };
+}
+function fromOverlayRenderableField(overlay) {
+  return {
+    fieldId: overlay.key,
+    title: overlay.label ?? overlay.key,
+    visible: overlay.visible ?? true,
+    required: overlay.required ?? false
+  };
+}
+function toOverlayRenderable(fields) {
+  return {
+    fields: fields.map(toOverlayRenderableField)
+  };
+}
+function mergeOverlayResultIntoFields(fields, merged) {
+  const fieldMap = new Map(fields.map((f) => [f.fieldId, { ...f }]));
+  const result = [];
+  for (const overlay of merged.fields) {
+    const existing = fieldMap.get(overlay.key);
+    if (existing) {
+      result.push({
+        ...existing,
+        title: overlay.label ?? existing.title,
+        visible: overlay.visible ?? existing.visible,
+        required: overlay.required ?? existing.required
+      });
+    }
+  }
+  return result;
+}
+function applyEntityFieldOverlays(fields, overlays, options) {
+  if (!overlays.length)
+    return fields;
+  const target = toOverlayRenderable(fields);
+  const merged = applyOverlayModifications(target, overlays, options);
+  return mergeOverlayResultIntoFields(fields, merged);
+}
+export {
+  toOverlayTargetRef,
+  toOverlayScopeContext,
+  toOverlayRenderableField,
+  toOverlayRenderable,
+  toOverlayAppliesTo,
+  mergeOverlayResultIntoFields,
+  fromOverlayRenderableField,
+  applyEntityFieldOverlays
+};

package/dist/node/runtime/overlay-signer.js

@@ -0,0 +1,15 @@
+// src/runtime/overlay-signer.ts
+import {
+  signOverlay,
+  verifyOverlaySignature
+} from "@contractspec/lib.overlay-engine/signer";
+function signWorkspaceOverlay(spec, privateKey, options) {
+  return signOverlay(spec, privateKey, options);
+}
+function verifyWorkspaceOverlay(overlay) {
+  return verifyOverlaySignature(overlay);
+}
+export {
+  verifyWorkspaceOverlay,
+  signWorkspaceOverlay
+};

package/dist/node/runtime/override-store.js

@@ -0,0 +1,52 @@
+// src/runtime/override-store.ts
+function buildOverrideTargetKey(bundleKey, surfaceId, routeId) {
+  return routeId ? `${bundleKey}:${routeId}:${surfaceId}` : `${bundleKey}:${surfaceId}`;
+}
+function createOverrideStoreWithApprovalGate(store, options) {
+  const { requireApprovalForWorkspacePatches = false, requestApproval } = options;
+  return {
+    list: store.list.bind(store),
+    async save(scope, targetKey, patch, saveOptions) {
+      if (requireApprovalForWorkspacePatches && scope === "workspace" && requestApproval) {
+        const approved = await requestApproval({ scope, targetKey, patch });
+        if (!approved) {
+          throw new Error("Workspace overlay save rejected: approval required and not granted");
+        }
+      }
+      return store.save(scope, targetKey, patch, saveOptions);
+    },
+    remove: store.remove.bind(store)
+  };
+}
+function createInMemoryOverrideStore() {
+  const overrides = new Map;
+  function nextId() {
+    return `ov_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+  return {
+    async list(scope, targetKey) {
+      return Array.from(overrides.values()).filter((o) => o.scope === scope && o.targetKey === targetKey);
+    },
+    async save(scope, targetKey, patch, options) {
+      const overrideId = options?.overrideId ?? nextId();
+      const stored = {
+        overrideId,
+        scope,
+        targetKey,
+        patch,
+        createdAt: new Date().toISOString(),
+        createdBy: options?.createdBy
+      };
+      overrides.set(overrideId, stored);
+      return overrideId;
+    },
+    async remove(overrideId) {
+      overrides.delete(overrideId);
+    }
+  };
+}
+export {
+  createOverrideStoreWithApprovalGate,
+  createInMemoryOverrideStore,
+  buildOverrideTargetKey
+};

package/dist/node/runtime/planner-prompt.js

@@ -0,0 +1,67 @@
+// src/runtime/planner-prompt.ts
+var SAFETY_INSTRUCTIONS = `
+## Safety instructions (mandatory)
+- Do NOT emit JSX, HTML, or raw markup.
+- Do NOT invent node kinds; use only the allowed kinds listed above.
+- Do NOT call undeclared tools.
+- Prefer fewer high-confidence patches over many speculative ones.
+- Explain why a patch helps the user.
+`;
+function compilePlannerPrompt(input) {
+  const {
+    bundleMeta,
+    surfaceId,
+    allowedPatchOps,
+    allowedSlots,
+    allowedNodeKinds,
+    actions,
+    preferences,
+    basePrompt,
+    planSummary,
+    entity
+  } = input;
+  const parts = [];
+  parts.push(`# Bundle: ${bundleMeta.title} (${bundleMeta.key}@${bundleMeta.version})`);
+  parts.push(`# Surface: ${surfaceId}`);
+  parts.push("");
+  if (basePrompt) {
+    parts.push("## Base instructions");
+    parts.push(basePrompt);
+    parts.push("");
+  }
+  parts.push("## Allowed patch operations");
+  parts.push(allowedPatchOps.join(", "));
+  parts.push("");
+  parts.push("## Allowed slots");
+  parts.push(allowedSlots.join(", "));
+  parts.push("");
+  parts.push("## Allowed node kinds");
+  parts.push(allowedNodeKinds.join(", "));
+  parts.push("");
+  if (actions.length > 0) {
+    parts.push("## Visible actions");
+    for (const a of actions) {
+      parts.push(`- ${a.actionId}: ${a.title}`);
+    }
+    parts.push("");
+  }
+  parts.push("## Current preference profile");
+  parts.push(`guidance=${preferences.guidance}, density=${preferences.density}, ` + `dataDepth=${preferences.dataDepth}, control=${preferences.control}, ` + `media=${preferences.media}, pace=${preferences.pace}, narrative=${preferences.narrative}`);
+  parts.push("");
+  if (planSummary) {
+    parts.push("## Current plan summary");
+    parts.push(planSummary);
+    parts.push("");
+  }
+  if (entity) {
+    parts.push("## Entity context");
+    parts.push(`${entity.type}: ${entity.id}`);
+    parts.push("");
+  }
+  parts.push(SAFETY_INSTRUCTIONS.trim());
+  return parts.join(`
+`);
+}
+export {
+  compilePlannerPrompt
+};

package/dist/node/runtime/planner-tools.js

@@ -0,0 +1,77 @@
+// src/runtime/planner-tools.ts
+var PROPOSE_PATCH_TOOL_SCHEMA = {
+  type: "object",
+  properties: {
+    proposalId: { type: "string", description: "Unique proposal identifier" },
+    ops: {
+      type: "array",
+      description: "Surface patch operations to propose",
+      items: {
+        type: "object",
+        required: ["op"],
+        properties: {
+          op: {
+            type: "string",
+            enum: [
+              "insert-node",
+              "replace-node",
+              "remove-node",
+              "move-node",
+              "resize-panel",
+              "set-layout",
+              "reveal-field",
+              "hide-field",
+              "promote-action",
+              "set-focus"
+            ]
+          },
+          slotId: { type: "string" },
+          nodeId: { type: "string" },
+          toSlotId: { type: "string" },
+          index: { type: "number" },
+          node: {
+            type: "object",
+            properties: {
+              nodeId: { type: "string" },
+              kind: { type: "string" },
+              title: { type: "string" },
+              props: { type: "object" },
+              children: { type: "array" }
+            }
+          },
+          persistKey: { type: "string" },
+          sizes: { type: "array", items: { type: "number" } },
+          layoutId: { type: "string" },
+          fieldId: { type: "string" },
+          actionId: { type: "string" },
+          placement: {
+            type: "string",
+            enum: ["header", "inline", "context", "assistant"]
+          },
+          targetId: { type: "string" }
+        }
+      }
+    }
+  },
+  required: ["proposalId", "ops"]
+};
+var proposePatchToolConfig = {
+  name: "propose-patch",
+  description: "Propose surface patches (layout changes, node insertions, etc.) for user approval. " + "Only use allowed ops, slots, and node kinds from the planner context.",
+  schema: PROPOSE_PATCH_TOOL_SCHEMA,
+  automationSafe: false,
+  requiresApproval: true
+};
+function buildSurfacePatchProposal(proposalId, ops) {
+  return {
+    proposalId,
+    source: "assistant",
+    ops,
+    approvalState: "proposed"
+  };
+}
+export {
+  proposePatchToolConfig,
+  buildSurfacePatchProposal,
+  PROPOSE_PATCH_TOOL_SCHEMA
+};

package/dist/node/runtime/policy-eval.js

@@ -0,0 +1,155 @@
+// 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
+    }
+  });
+}
+
+// src/runtime/policy-eval.ts
+function evaluatePatchProposalPolicy(ops, ctx, policy) {
+  const evaluate = policy?.evaluatePatchProposal;
+  if (!evaluate)
+    return "allow";
+  return evaluate(ops, ctx);
+}
+function evaluateAndEmitPatchPolicy(ops, ctx, args) {
+  const effect = evaluatePatchProposalPolicy(ops, ctx, args.policy);
+  if (effect === "deny") {
+    if (args.audit) {
+      emitPolicyDenied(args.audit, {
+        bundleKey: args.bundleKey,
+        surfaceId: args.surfaceId,
+        targetId: args.targetId ?? "patch-proposal",
+        reason: "Policy denied patch proposal",
+        actorId: ctx.actorId
+      });
+    }
+    return false;
+  }
+  return true;
+}
+export {
+  evaluatePatchProposalPolicy,
+  evaluateAndEmitPatchPolicy
+};

package/dist/node/runtime/preference-adapter.js

@@ -0,0 +1,67 @@
+// 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
+  };
+}
+
+// src/runtime/preference-adapter.ts
+var defaultPreferenceAdapter = {
+  async resolve(ctx) {
+    return resolvePreferenceProfile(ctx);
+  },
+  async savePreferencePatch(_args) {}
+};
+export {
+  defaultPreferenceAdapter
+};