@contractspec/lib.surface-runtime 0.2.0

package/dist/runtime/policy-eval.js

@@ -0,0 +1,156 @@
+// @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
+    }
+  });
+}
+
+// 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/runtime/preference-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { BundlePreferenceAdapter } from '../spec/types';
+/**
+ * Default preference adapter. Uses in-memory resolution; savePreferencePatch is a no-op stub.
+ * Integrate with lib.personalization or lib.overlay-engine for persistence.
+ */
+export declare const defaultPreferenceAdapter: BundlePreferenceAdapter;

package/dist/runtime/preference-adapter.js

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

package/dist/runtime/resolve-bundle.d.ts

@@ -0,0 +1,68 @@
+import type { ActionSpec, AppliedOverlayMeta, BundleContext, BundleScope, CommandSpec, ModuleBundleSpec, RegionNode, ResolvedAdaptation, SurfaceNode, SurfacePatchProposal, UiPolicyDecision, BundleAuditEmitter } from '../spec/types';
+import type { BundleOverrideStore } from './override-store';
+export interface OverlayConflict {
+    targetKey: string;
+    scopeA: BundleScope;
+    scopeB: BundleScope;
+    overlayIdA: string;
+    overlayIdB: string;
+}
+export interface ResolvedSurfacePlan {
+    bundleKey: string;
+    surfaceId: string;
+    layoutId: string;
+    /** Resolved layout root for rendering. */
+    layoutRoot: RegionNode;
+    nodes: SurfaceNode[];
+    actions: ActionSpec[];
+    commands: CommandSpec[];
+    bindings: Record<string, unknown>;
+    adaptation: ResolvedAdaptation;
+    overlays: AppliedOverlayMeta[];
+    overlayConflicts?: OverlayConflict[];
+    ai: {
+        plannerId?: string;
+        proposals?: SurfacePatchProposal[];
+    };
+    audit: {
+        resolutionId: string;
+        createdAt: string;
+        reasons: string[];
+    };
+    /** Locale for i18n (from BundleContext). Used by UI components. */
+    locale?: string;
+}
+/** Policy effect for patch proposal evaluation. */
+export type PatchPolicyEffect = 'allow' | 'deny' | 'require-approval';
+/** Policy hooks for PDP integration. Stub PDP returns allow by default. */
+export interface PolicyHooks<C extends BundleContext> {
+    /** Evaluate node visibility. Return allow/deny/redact. Stub: allow all. */
+    evaluateNode?: (node: SurfaceNode, ctx: C) => UiPolicyDecision;
+    /** Redact binding value. Stub: pass-through. */
+    redactBinding?: (key: string, ctx: C) => unknown;
+    /** Evaluate patch proposal before approval. Stub: allow. */
+    evaluatePatchProposal?: (ops: import('../spec/types').SurfacePatchOp[], ctx: C) => PatchPolicyEffect;
+}
+export interface OverlayMergeOptions {
+    overrideStore: BundleOverrideStore;
+    /** Scopes to fetch (default: system, workspace, user, session). */
+    scopes?: BundleScope[];
+}
+export interface ResolveBundleOptions<C extends BundleContext> {
+    /** Optional policy hooks for allow/deny/redact. Stub PDP returns allow. */
+    policy?: PolicyHooks<C>;
+    /** Optional audit emitter. Emits surface.resolved on resolution. */
+    audit?: BundleAuditEmitter;
+    /** Optional overlay merge. Applies stored overlays in precedence order. */
+    overlayMerge?: OverlayMergeOptions;
+}
+/**
+ * Resolves a bundle spec and context into a concrete surface plan.
+ * Fallback chain: surface → simpler layout → overview → error surface.
+ *
+ * @param spec - The module bundle spec
+ * @param ctx - The bundle context (route, preferences, etc.)
+ * @param options - Optional policy hooks
+ * @returns Resolved surface plan with layout, nodes, bindings, and audit
+ */
+export declare function resolveBundle<C extends BundleContext>(spec: ModuleBundleSpec<C>, ctx: C, options?: ResolveBundleOptions<C>): Promise<ResolvedSurfacePlan>;