@contractspec/lib.surface-runtime 0.2.0

package/dist/runtime/overlay-alignment.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Overlay alignment: maps surface runtime types to lib.overlay-engine.
+ * Aligns with 09_extension_and_override_model.md.
+ *
+ * OverlayTargetRef: capability, workflow, dataView, presentation, operation.
+ * OverlayRenderableField: key, label, visible, required, helpText, defaultValue, order.
+ * OverlayScopeContext: tenantId, role, userId, device, tags.
+ */
+import type { OverlayTargetRef, OverlayScopeContext, OverlayAppliesTo, SignedOverlaySpec } from '@contractspec/lib.overlay-engine/spec';
+import type { OverlayRenderableField } from '@contractspec/lib.overlay-engine/types';
+import type { BundleContext, ResolvedField, BundleScope } from '../spec/types';
+/** Surface-specific target ref extensions for overlay matching. */
+export interface SurfaceOverlayTargetRef extends OverlayTargetRef {
+    /** Bundle key (e.g. "workspace.pm"). */
+    bundleKey?: string;
+    /** Surface ID (e.g. "issue-detail"). */
+    surfaceId?: string;
+    /** Route ID (e.g. "issue-detail"). */
+    routeId?: string;
+    /** Entity type when targeting entity surfaces (e.g. "pm.issue"). */
+    entityType?: string;
+}
+/** Build OverlayScopeContext from BundleContext. */
+export declare function toOverlayScopeContext(ctx: BundleContext): OverlayScopeContext;
+/** Build OverlayTargetRef from BundleContext and surface target. */
+export declare function toOverlayTargetRef(_ctx: BundleContext, target: {
+    bundleKey?: string;
+    surfaceId?: string;
+    routeId?: string;
+    entityType?: string;
+}): SurfaceOverlayTargetRef;
+/** Build OverlayAppliesTo for surface overlays. */
+export declare function toOverlayAppliesTo(ctx: BundleContext, target: SurfaceOverlayTargetRef, scope: BundleScope): OverlayAppliesTo;
+/** Map ResolvedField to OverlayRenderableField. */
+export declare function toOverlayRenderableField(field: ResolvedField): OverlayRenderableField;
+/** Map OverlayRenderableField back to partial ResolvedField (for merge result). */
+export declare function fromOverlayRenderableField(overlay: OverlayRenderableField): Partial<ResolvedField>;
+/** Convert ResolvedEntitySchema fields to OverlayRenderable for overlay-engine merger. */
+export declare function toOverlayRenderable(fields: ResolvedField[]): {
+    fields: OverlayRenderableField[];
+};
+/** Apply overlay-engine merger result back to ResolvedField[]. */
+export declare function mergeOverlayResultIntoFields(fields: ResolvedField[], merged: {
+    fields: OverlayRenderableField[];
+}): ResolvedField[];
+/** Apply overlay-engine merger to entity fields. Returns merged ResolvedField[]. */
+export declare function applyEntityFieldOverlays(fields: ResolvedField[], overlays: SignedOverlaySpec[], options?: {
+    strict?: boolean;
+}): ResolvedField[];

package/dist/runtime/overlay-alignment.js

@@ -0,0 +1,84 @@
+// @bun
+// 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/runtime/overlay-alignment.test.d.ts

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

package/dist/runtime/overlay-signer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workspace overlay signing using lib.overlay-engine signer.
+ * Aligns with 09_extension_and_override_model.md.
+ *
+ * Workspace overlays require signing for audit and provenance.
+ * Never use ephemeral-ai trust for durable registration.
+ */
+import { type SignOverlayOptions } from '@contractspec/lib.overlay-engine/signer';
+import type { OverlaySpec, SignedOverlaySpec } from '@contractspec/lib.overlay-engine/spec';
+/** Private key for signing (PEM string, Buffer, or crypto.KeyObject). */
+export type OverlaySigningKey = string | Buffer | import('crypto').KeyLike;
+/** Sign a workspace overlay for durable persistence. */
+export declare function signWorkspaceOverlay(spec: OverlaySpec, privateKey: OverlaySigningKey, options?: SignOverlayOptions): SignedOverlaySpec;
+/** Verify a signed workspace overlay. */
+export declare function verifyWorkspaceOverlay(overlay: SignedOverlaySpec): boolean;

package/dist/runtime/overlay-signer.js

@@ -0,0 +1,16 @@
+// @bun
+// 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/runtime/override-store.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Overlay persistence for surface runtime.
+ * Aligns with 09_extension_and_override_model.md.
+ *
+ * Merge order: base → system → workspace → user → session → AI proposals.
+ * User and workspace overlays are durable; session and AI are ephemeral.
+ */
+import type { BundleScope, SurfacePatchOp } from '../spec/types';
+export interface StoredOverride {
+    overrideId: string;
+    scope: BundleScope;
+    targetKey: string;
+    patch: SurfacePatchOp[];
+    createdAt: string;
+    createdBy?: string;
+}
+export interface BundleOverrideStore {
+    list(scope: BundleScope, targetKey: string): Promise<StoredOverride[]>;
+    save(scope: BundleScope, targetKey: string, patch: SurfacePatchOp[], options?: {
+        overrideId?: string;
+        createdBy?: string;
+    }): Promise<string>;
+    remove(overrideId: string): Promise<void>;
+}
+/** Build target key for overlay lookup (bundleKey:surfaceId or bundleKey:routeId). */
+export declare function buildOverrideTargetKey(bundleKey: string, surfaceId: string, routeId?: string): string;
+export interface ApprovalGateOptions {
+    /** When true, workspace scope saves require approval before persisting. */
+    requireApprovalForWorkspacePatches?: boolean;
+    /** Called when workspace save is attempted. Return true to allow, false to reject. */
+    requestApproval?: (args: {
+        scope: BundleScope;
+        targetKey: string;
+        patch: SurfacePatchOp[];
+    }) => Promise<boolean>;
+}
+/**
+ * Wraps a store with an approval gate for workspace overlays.
+ * When requireApprovalForWorkspacePatches is true and scope is 'workspace',
+ * calls requestApproval before save. Rejects if requestApproval returns false.
+ */
+export declare function createOverrideStoreWithApprovalGate(store: BundleOverrideStore, options: ApprovalGateOptions): BundleOverrideStore;
+/** In-memory override store. For production, replace with persisted backend. */
+export declare function createInMemoryOverrideStore(): BundleOverrideStore;

package/dist/runtime/override-store.js

@@ -0,0 +1,53 @@
+// @bun
+// 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/runtime/override-store.test.d.ts

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

package/dist/runtime/planner-prompt.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Planner prompt compiler for AI-native surface patches.
+ * Compiles bundle metadata, allowed ops, slots, and node kinds into a system prompt.
+ * Aligns with 07_ai_native_chat_and_generative_ui.md.
+ */
+import type { BundleMeta, BundleNodeKind, PreferenceDimensions, SurfacePatchOp } from '../spec/types';
+import type { ActionSpec } from '../spec/types';
+export interface PlannerPromptInput {
+    /** Bundle metadata. */
+    bundleMeta: BundleMeta;
+    /** Current surface ID. */
+    surfaceId: string;
+    /** Allowed patch operations. */
+    allowedPatchOps: SurfacePatchOp['op'][];
+    /** Allowed slot IDs for insert-node and move-node. */
+    allowedSlots: string[];
+    /** Allowed node kinds for new nodes. */
+    allowedNodeKinds: BundleNodeKind[];
+    /** Visible actions (actionId, title). */
+    actions: Pick<ActionSpec, 'actionId' | 'title'>[];
+    /** Current preference profile. */
+    preferences: PreferenceDimensions;
+    /** Optional base planner prompt from spec. */
+    basePrompt?: string;
+    /** Optional plan summary (e.g. layout, node count). */
+    planSummary?: string;
+    /** Optional entity metadata. */
+    entity?: {
+        type: string;
+        id: string;
+    };
+}
+/**
+ * Compiles planner prompt from bundle and surface context.
+ *
+ * @param input - Bundle metadata, allowed ops, slots, node kinds, preferences
+ * @returns System prompt string for the planner
+ */
+export declare function compilePlannerPrompt(input: PlannerPromptInput): string;

package/dist/runtime/planner-prompt.js

@@ -0,0 +1,68 @@
+// @bun
+// 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/runtime/planner-prompt.test.d.ts

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

package/dist/runtime/planner-tools.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Planner tool schemas for ContractSpecAgent/AgentSpec.
+ * Maps to AgentToolConfig; tool handlers are wired by the bundle layer.
+ * Aligns with 07_ai_native_chat_and_generative_ui.md.
+ */
+import type { SurfacePatchProposal } from '../spec/types';
+/** Compatible with AgentToolConfig from @contractspec/lib.ai-agent. */
+export interface PlannerToolConfig {
+    name: string;
+    description?: string;
+    schema?: Record<string, unknown>;
+    automationSafe?: boolean;
+    requiresApproval?: boolean;
+}
+/** JSON Schema for propose-patch tool parameters. */
+export declare const PROPOSE_PATCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly proposalId: {
+            readonly type: "string";
+            readonly description: "Unique proposal identifier";
+        };
+        readonly ops: {
+            readonly type: "array";
+            readonly description: "Surface patch operations to propose";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["op"];
+                readonly properties: {
+                    readonly op: {
+                        readonly type: "string";
+                        readonly enum: readonly ["insert-node", "replace-node", "remove-node", "move-node", "resize-panel", "set-layout", "reveal-field", "hide-field", "promote-action", "set-focus"];
+                    };
+                    readonly slotId: {
+                        readonly type: "string";
+                    };
+                    readonly nodeId: {
+                        readonly type: "string";
+                    };
+                    readonly toSlotId: {
+                        readonly type: "string";
+                    };
+                    readonly index: {
+                        readonly type: "number";
+                    };
+                    readonly node: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly nodeId: {
+                                readonly type: "string";
+                            };
+                            readonly kind: {
+                                readonly type: "string";
+                            };
+                            readonly title: {
+                                readonly type: "string";
+                            };
+                            readonly props: {
+                                readonly type: "object";
+                            };
+                            readonly children: {
+                                readonly type: "array";
+                            };
+                        };
+                    };
+                    readonly persistKey: {
+                        readonly type: "string";
+                    };
+                    readonly sizes: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly layoutId: {
+                        readonly type: "string";
+                    };
+                    readonly fieldId: {
+                        readonly type: "string";
+                    };
+                    readonly actionId: {
+                        readonly type: "string";
+                    };
+                    readonly placement: {
+                        readonly type: "string";
+                        readonly enum: readonly ["header", "inline", "context", "assistant"];
+                    };
+                    readonly targetId: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+    readonly required: readonly ["proposalId", "ops"];
+};
+/**
+ * Tool config for propose-patch. Use with ContractSpecAgent toolHandlers.
+ * Handler should validate via validatePatchProposal and return SurfacePatchProposal.
+ */
+export declare const proposePatchToolConfig: PlannerToolConfig;
+/**
+ * Builds a SurfacePatchProposal from validated tool output.
+ * Call after validatePatchProposal passes.
+ */
+export declare function buildSurfacePatchProposal(proposalId: string, ops: SurfacePatchProposal['ops']): SurfacePatchProposal;

package/dist/runtime/planner-tools.js

@@ -0,0 +1,78 @@
+// @bun
+// 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/runtime/planner-tools.test.d.ts

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

package/dist/runtime/policy-eval.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Policy evaluation helpers for patch proposals.
+ * Gate patch application with PDP; emit policy.denied when blocked.
+ */
+import type { BundleContext, SurfacePatchOp, BundleAuditEmitter } from '../spec/types';
+import type { PolicyHooks, PatchPolicyEffect } from './resolve-bundle';
+/**
+ * Evaluates a patch proposal with policy hooks.
+ * Returns allow | deny | require-approval.
+ * When policy hook is absent, returns allow (stub PDP).
+ */
+export declare function evaluatePatchProposalPolicy<C extends BundleContext>(ops: SurfacePatchOp[], ctx: C, policy?: PolicyHooks<C>): PatchPolicyEffect;
+/**
+ * Evaluates and optionally emits policy.denied when blocked.
+ * Call before applying patches. If returns false, do not apply.
+ */
+export declare function evaluateAndEmitPatchPolicy<C extends BundleContext>(ops: SurfacePatchOp[], ctx: C, args: {
+    policy?: PolicyHooks<C>;
+    audit?: BundleAuditEmitter;
+    bundleKey: string;
+    surfaceId?: string;
+    targetId?: string;
+}): boolean;