@panproto/core 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -30,6 +30,10 @@ export { Instance } from './instance.js';
 export { IoRegistry, PROTOCOL_CATEGORIES } from './io.js';
 export { FullDiffReport, CompatReport, ValidationResult } from './check.js';
 export type { FullSchemaDiff, CompatReportData, BreakingChange, NonBreakingChange, ConstraintChange, ConstraintDiff, KindChange, SchemaValidationIssue, } from './types.js';
+export { SchemaEnrichment } from './enrichment.js';
+export { ExprBuilder } from './expr.js';
+export { MigrationAnalysis } from './coverage.js';
+export type { ValueKind, SortKind, DirectedEquation, ConflictStrategy, ConflictPolicy, Pattern, Expr, Literal, BuiltinOp, CoverageReport, PartialFailure, PartialReason, OpticKind, EnrichmentSummary, } from './types.js';
 export type { LawCheckResult, ProtocolSpec, EdgeRule, Vertex, Edge, HyperEdge, Constraint, Variant, RecursionPoint, UsageMode, Span, VertexOptions, EdgeOptions, SchemaData, MigrationSpec, LiftResult, GetResult, DiffReport, SchemaChange, Compatibility, ExistenceReport, ExistenceError, WasmModule, WasmExports, InstanceShape, InstanceValidationResult, } from './types.js';
 export { TheoryHandle, TheoryBuilder, createTheory, colimit, checkMorphism, migrateModel, factorizeMorphism, } from './gat.js';
 export type { TheorySpec, TheoryMorphism, Sort, SortParam, GatOperation, Equation, Term, MorphismCheckResult, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGrE,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,SAAS,EACT,UAAU,EACV,OAAO,EACP,cAAc,EACd,SAAS,EACT,IAAI,EACJ,aAAa,EACb,WAAW,EACX,UAAU,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,YAAY,EACZ,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,UAAU,EACV,cAAc,EACd,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,IAAI,EACJ,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EACL,aAAa,EACb,SAAS,EACT,qBAAqB,EACrB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGrE,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD,YAAY,EACV,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,OAAO,EACP,IAAI,EACJ,OAAO,EACP,SAAS,EACT,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,SAAS,EACT,UAAU,EACV,OAAO,EACP,cAAc,EACd,SAAS,EACT,IAAI,EACJ,aAAa,EACb,WAAW,EACX,UAAU,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,YAAY,EACZ,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,UAAU,EACV,cAAc,EACd,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,IAAI,EACJ,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EACL,aAAa,EACb,SAAS,EACT,qBAAqB,EACrB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2057,6 +2057,10 @@ class Panproto {
     this.#wasm = wasm;
     this.#protocols = /* @__PURE__ */ new Map();
   }
+  /** The WASM module reference. Internal use only. */
+  get _wasm() {
+    return this.#wasm;
+  }
   /**
    * Initialize the panproto SDK by loading the WASM module.
    *
@@ -2362,6 +2366,535 @@ class Panproto {
     this.#protocols.clear();
   }
 }
+class SchemaEnrichment {
+  #schema;
+  #defaults;
+  #coercions;
+  #mergers;
+  #policies;
+  constructor(schema, defaults = [], coercions = [], mergers = [], policies = []) {
+    this.#schema = schema;
+    this.#defaults = defaults;
+    this.#coercions = coercions;
+    this.#mergers = mergers;
+    this.#policies = policies;
+  }
+  /**
+   * Add a default expression for a vertex.
+   *
+   * The expression is evaluated when forward migration encounters a
+   * missing value at the given vertex.
+   *
+   * @param vertex - The vertex identifier to attach the default to
+   * @param expr - The default expression
+   * @returns A new enrichment with the default added
+   * @throws {@link PanprotoError} if the vertex is not in the schema
+   */
+  addDefault(vertex, expr) {
+    this.#assertVertex(vertex);
+    if (this.#defaults.some((d) => d.vertex === vertex)) {
+      throw new PanprotoError(
+        `Default already exists for vertex "${vertex}". Remove it first with removeDefault().`
+      );
+    }
+    return new SchemaEnrichment(
+      this.#schema,
+      [...this.#defaults, { vertex, expr }],
+      this.#coercions,
+      this.#mergers,
+      this.#policies
+    );
+  }
+  /**
+   * Add a coercion function between two value kinds.
+   *
+   * The expression defines how to convert values from `fromKind` to
+   * `toKind`. It receives a single argument (the source value) and
+   * must produce a value of the target kind.
+   *
+   * @param fromKind - Source value kind (e.g., 'int')
+   * @param toKind - Target value kind (e.g., 'float')
+   * @param expr - The coercion expression
+   * @returns A new enrichment with the coercion added
+   * @throws {@link PanprotoError} if a coercion for this pair already exists
+   */
+  addCoercion(fromKind, toKind, expr) {
+    if (this.#coercions.some((c) => c.from === fromKind && c.to === toKind)) {
+      throw new PanprotoError(
+        `Coercion from "${fromKind}" to "${toKind}" already exists. Remove it first with removeCoercion().`
+      );
+    }
+    return new SchemaEnrichment(
+      this.#schema,
+      this.#defaults,
+      [...this.#coercions, { from: fromKind, to: toKind, expr }],
+      this.#mergers,
+      this.#policies
+    );
+  }
+  /**
+   * Add a merger expression for a vertex.
+   *
+   * The expression defines how to merge two conflicting values at the
+   * given vertex. It receives two arguments (left and right values)
+   * and must produce a single merged value.
+   *
+   * @param vertex - The vertex identifier to attach the merger to
+   * @param expr - The merger expression
+   * @returns A new enrichment with the merger added
+   * @throws {@link PanprotoError} if the vertex is not in the schema
+   */
+  addMerger(vertex, expr) {
+    this.#assertVertex(vertex);
+    if (this.#mergers.some((m) => m.vertex === vertex)) {
+      throw new PanprotoError(
+        `Merger already exists for vertex "${vertex}". Remove it first.`
+      );
+    }
+    return new SchemaEnrichment(
+      this.#schema,
+      this.#defaults,
+      this.#coercions,
+      [...this.#mergers, { vertex, expr }],
+      this.#policies
+    );
+  }
+  /**
+   * Add a conflict resolution policy for a vertex.
+   *
+   * @param vertex - The vertex identifier
+   * @param strategy - The conflict resolution strategy
+   * @returns A new enrichment with the policy added
+   * @throws {@link PanprotoError} if the vertex is not in the schema
+   */
+  addPolicy(vertex, strategy) {
+    this.#assertVertex(vertex);
+    if (this.#policies.some((p) => p.vertex === vertex)) {
+      throw new PanprotoError(
+        `Policy already exists for vertex "${vertex}". Remove it first.`
+      );
+    }
+    return new SchemaEnrichment(
+      this.#schema,
+      this.#defaults,
+      this.#coercions,
+      this.#mergers,
+      [...this.#policies, { vertex, strategy }]
+    );
+  }
+  /**
+   * Remove the default expression for a vertex.
+   *
+   * @param vertex - The vertex identifier
+   * @returns A new enrichment with the default removed
+   * @throws {@link PanprotoError} if no default exists for the vertex
+   */
+  removeDefault(vertex) {
+    const filtered = this.#defaults.filter((d) => d.vertex !== vertex);
+    if (filtered.length === this.#defaults.length) {
+      throw new PanprotoError(
+        `No default exists for vertex "${vertex}".`
+      );
+    }
+    return new SchemaEnrichment(
+      this.#schema,
+      filtered,
+      this.#coercions,
+      this.#mergers,
+      this.#policies
+    );
+  }
+  /**
+   * Remove the coercion function for a value kind pair.
+   *
+   * @param fromKind - Source value kind
+   * @param toKind - Target value kind
+   * @returns A new enrichment with the coercion removed
+   * @throws {@link PanprotoError} if no coercion exists for the pair
+   */
+  removeCoercion(fromKind, toKind) {
+    const filtered = this.#coercions.filter(
+      (c) => !(c.from === fromKind && c.to === toKind)
+    );
+    if (filtered.length === this.#coercions.length) {
+      throw new PanprotoError(
+        `No coercion exists from "${fromKind}" to "${toKind}".`
+      );
+    }
+    return new SchemaEnrichment(
+      this.#schema,
+      this.#defaults,
+      filtered,
+      this.#mergers,
+      this.#policies
+    );
+  }
+  /**
+   * List all enrichments currently attached.
+   *
+   * @returns An enrichment summary with defaults, coercions, mergers, and policies
+   */
+  listEnrichments() {
+    return {
+      defaults: this.#defaults.map((d) => ({ vertex: d.vertex, expr: d.expr })),
+      coercions: this.#coercions.map((c) => ({ from: c.from, to: c.to, expr: c.expr })),
+      mergers: this.#mergers.map((m) => ({ vertex: m.vertex, expr: m.expr })),
+      policies: this.#policies.map((p) => ({ vertex: p.vertex, strategy: p.strategy }))
+    };
+  }
+  /**
+   * Build the enriched schema.
+   *
+   * Returns a new `BuiltSchema` with the enrichments recorded in the
+   * schema data. The underlying WASM handle is shared with the original
+   * schema (enrichments are metadata that the SDK tracks client-side).
+   *
+   * @returns A new BuiltSchema with enrichment metadata
+   */
+  build() {
+    const originalData = this.#schema.data;
+    const enrichedData = {
+      ...originalData,
+      constraints: {
+        ...originalData.constraints
+      }
+    };
+    const enrichedConstraints = { ...enrichedData.constraints };
+    for (const def of this.#defaults) {
+      const existing = enrichedConstraints[def.vertex] ?? [];
+      enrichedConstraints[def.vertex] = [
+        ...existing,
+        { sort: "__default", value: JSON.stringify(def.expr) }
+      ];
+    }
+    for (const coercion of this.#coercions) {
+      const key = `__coercion:${coercion.from}:${coercion.to}`;
+      const existing = enrichedConstraints[key] ?? [];
+      enrichedConstraints[key] = [
+        ...existing,
+        { sort: "__coercion", value: JSON.stringify(coercion.expr) }
+      ];
+    }
+    for (const merger of this.#mergers) {
+      const existing = enrichedConstraints[merger.vertex] ?? [];
+      enrichedConstraints[merger.vertex] = [
+        ...existing,
+        { sort: "__merger", value: JSON.stringify(merger.expr) }
+      ];
+    }
+    for (const policy of this.#policies) {
+      const existing = enrichedConstraints[policy.vertex] ?? [];
+      enrichedConstraints[policy.vertex] = [
+        ...existing,
+        { sort: "__policy", value: JSON.stringify(policy.strategy) }
+      ];
+    }
+    const enrichedSchemaData = {
+      ...enrichedData,
+      constraints: enrichedConstraints
+    };
+    return new BuiltSchema(
+      this.#schema._handle,
+      enrichedSchemaData,
+      this.#schema._wasm
+    );
+  }
+  /**
+   * Assert that a vertex exists in the schema.
+   *
+   * @param vertex - The vertex to check
+   * @throws {@link PanprotoError} if the vertex is not found
+   */
+  #assertVertex(vertex) {
+    if (!(vertex in this.#schema.vertices)) {
+      throw new PanprotoError(
+        `Vertex "${vertex}" not found in schema. Available vertices: ${Object.keys(this.#schema.vertices).join(", ")}`
+      );
+    }
+  }
+}
+class ExprBuilder {
+  /** This class is not instantiable; all methods are static. */
+  constructor() {
+  }
+  /**
+   * Create a variable reference expression.
+   *
+   * @param name - The variable name to reference
+   * @returns A variable expression node
+   */
+  static var_(name) {
+    return { type: "var", name };
+  }
+  /**
+   * Create a literal expression.
+   *
+   * @param value - The literal value
+   * @returns A literal expression node
+   */
+  static lit(value) {
+    return { type: "lit", value };
+  }
+  /**
+   * Create a lambda (anonymous function) expression.
+   *
+   * @param param - The parameter name
+   * @param body - The function body expression
+   * @returns A lambda expression node
+   */
+  static lam(param, body) {
+    return { type: "lam", param, body };
+  }
+  /**
+   * Create a function application expression.
+   *
+   * When multiple arguments are provided, they are applied left-to-right
+   * via currying: `app(f, a, b)` becomes `app(app(f, a), b)`.
+   *
+   * @param func - The function expression
+   * @param args - One or more argument expressions
+   * @returns An application expression node (possibly nested)
+   */
+  static app(func, ...args) {
+    let result = func;
+    for (const arg of args) {
+      result = { type: "app", func: result, arg };
+    }
+    return result;
+  }
+  /**
+   * Create a let-binding expression.
+   *
+   * Binds `value` to `name` in the scope of `body`.
+   *
+   * @param name - The variable name to bind
+   * @param value - The value expression to bind
+   * @param body - The body expression where the binding is in scope
+   * @returns A let expression node
+   */
+  static let_(name, value, body) {
+    return { type: "let", name, value, body };
+  }
+  /**
+   * Create a field access expression.
+   *
+   * @param expr - The record expression to access
+   * @param name - The field name
+   * @returns A field access expression node
+   */
+  static field(expr, name) {
+    return { type: "field", expr, name };
+  }
+  /**
+   * Create a record literal expression.
+   *
+   * @param fields - A mapping of field names to expressions
+   * @returns A record expression node
+   */
+  static record(fields) {
+    const entries = Object.entries(fields);
+    return { type: "record", fields: entries };
+  }
+  /**
+   * Create a list literal expression.
+   *
+   * @param items - The list element expressions
+   * @returns A list expression node
+   */
+  static list(...items) {
+    return { type: "list", items };
+  }
+  /**
+   * Create a pattern-match expression.
+   *
+   * @param scrutinee - The expression to match against
+   * @param arms - Pattern-expression pairs tried in order
+   * @returns A match expression node
+   */
+  static match_(scrutinee, arms) {
+    return { type: "match", scrutinee, arms };
+  }
+  /**
+   * Create a builtin operation expression.
+   *
+   * @param op - The builtin operation name
+   * @param args - Argument expressions for the operation
+   * @returns A builtin expression node
+   */
+  static builtin(op, ...args) {
+    return { type: "builtin", op, args };
+  }
+  /**
+   * Create an index expression for list or record access.
+   *
+   * @param expr - The collection expression
+   * @param index - The index expression
+   * @returns An index expression node
+   */
+  static index(expr, index) {
+    return { type: "index", expr, index };
+  }
+  // -----------------------------------------------------------------
+  // Convenience arithmetic helpers
+  // -----------------------------------------------------------------
+  /**
+   * Add two expressions.
+   *
+   * @param a - Left operand
+   * @param b - Right operand
+   * @returns A builtin 'Add' expression
+   */
+  static add(a, b) {
+    return ExprBuilder.builtin("Add", a, b);
+  }
+  /**
+   * Subtract two expressions.
+   *
+   * @param a - Left operand
+   * @param b - Right operand
+   * @returns A builtin 'Sub' expression
+   */
+  static sub(a, b) {
+    return ExprBuilder.builtin("Sub", a, b);
+  }
+  /**
+   * Multiply two expressions.
+   *
+   * @param a - Left operand
+   * @param b - Right operand
+   * @returns A builtin 'Mul' expression
+   */
+  static mul(a, b) {
+    return ExprBuilder.builtin("Mul", a, b);
+  }
+  /**
+   * Concatenate two expressions (strings or lists).
+   *
+   * @param a - Left operand
+   * @param b - Right operand
+   * @returns A builtin 'Concat' expression
+   */
+  static concat(a, b) {
+    return ExprBuilder.builtin("Concat", a, b);
+  }
+}
+function classifyOpticKind(chain, schema, _wasm) {
+  const spec = chain.requirements(schema);
+  const hasDefaults = spec.forwardDefaults.length > 0;
+  const hasCaptured = spec.capturedData.length > 0;
+  if (!hasDefaults && !hasCaptured && spec.kind === "empty") {
+    return "iso";
+  }
+  if (hasDefaults && hasCaptured) {
+    return "affine";
+  }
+  if (hasCaptured) {
+    return "lens";
+  }
+  if (hasDefaults) {
+    return "prism";
+  }
+  return "traversal";
+}
+function runDryRun(compiled, instances, srcSchema, _tgtSchema, wasm) {
+  const totalRecords = instances.length;
+  const failed = [];
+  let successful = 0;
+  let recordIndex = 0;
+  for (const record of instances) {
+    try {
+      const inputBytes = packToWasm(record);
+      const instanceBytes = wasm.exports.json_to_instance(
+        srcSchema._handle.id,
+        inputBytes
+      );
+      wasm.exports.lift_record(compiled._handle.id, instanceBytes);
+      successful++;
+    } catch (error) {
+      const reason = categorizeFailure(error);
+      failed.push({ recordId: recordIndex, reason });
+    }
+    recordIndex++;
+  }
+  const coverageRatio = totalRecords > 0 ? successful / totalRecords : 1;
+  return {
+    totalRecords,
+    successful,
+    failed,
+    coverageRatio
+  };
+}
+function categorizeFailure(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("constraint") || message.includes("Constraint")) {
+    const constraintMatch = /constraint\s+"?([^"]+)"?\s+violated.*?value\s+"?([^"]*)"?/i.exec(message);
+    return {
+      type: "constraint_violation",
+      constraint: constraintMatch?.[1] ?? "unknown",
+      value: constraintMatch?.[2] ?? "unknown"
+    };
+  }
+  if (message.includes("required") || message.includes("missing")) {
+    const fieldMatch = /(?:required|missing)\s+(?:field\s+)?"?([^"]+)"?/i.exec(message);
+    return {
+      type: "missing_required_field",
+      field: fieldMatch?.[1] ?? "unknown"
+    };
+  }
+  if (message.includes("type") && message.includes("mismatch")) {
+    const typeMatch = /expected\s+"?([^"]+)"?\s+got\s+"?([^"]+)"?/i.exec(message);
+    return {
+      type: "type_mismatch",
+      expected: typeMatch?.[1] ?? "unknown",
+      got: typeMatch?.[2] ?? "unknown"
+    };
+  }
+  return {
+    type: "expr_eval_failed",
+    exprName: "migration",
+    error: message
+  };
+}
+class MigrationAnalysis {
+  #wasm;
+  /**
+   * Create a new migration analysis instance.
+   *
+   * @param panproto - The Panproto instance providing WASM access
+   */
+  constructor(panproto) {
+    this.#wasm = panproto._wasm;
+  }
+  /**
+   * Run a dry-run migration and return a coverage report.
+   *
+   * Tests each instance record against the compiled migration without
+   * persisting results, producing detailed failure information for
+   * records that cannot be migrated.
+   *
+   * @param compiled - The compiled migration to test
+   * @param instances - Array of instance records (plain objects)
+   * @param srcSchema - The source schema the instances conform to
+   * @param tgtSchema - The target schema
+   * @returns A coverage report with per-record success/failure data
+   */
+  dryRun(compiled, instances, srcSchema, tgtSchema) {
+    return runDryRun(compiled, instances, srcSchema, tgtSchema, this.#wasm);
+  }
+  /**
+   * Classify the optic kind of a protolens chain.
+   *
+   * Determines whether the chain represents an isomorphism, lens, prism,
+   * affine transformation, or traversal based on its complement structure.
+   *
+   * @param chain - The protolens chain to classify
+   * @param schema - The schema to check the chain against
+   * @returns The optic kind classification
+   */
+  opticKind(chain, schema) {
+    return classifyOpticKind(chain, schema, this.#wasm);
+  }
+}
 class TheoryHandle {
   #handle;
   /** @internal Retained for future sort/op inspection methods. */
@@ -2501,12 +3034,14 @@ export {
   CompiledMigration,
   DataSetHandle,
   ExistenceCheckError,
+  ExprBuilder,
   FullDiffReport,
   GRAPHQL_SPEC,
   Instance,
   IoRegistry,
   JSON_SCHEMA_SPEC,
   LensHandle,
+  MigrationAnalysis,
   MigrationBuilder,
   MigrationError,
   PROTOBUF_SPEC,
@@ -2518,6 +3053,7 @@ export {
   Repository,
   SQL_SPEC,
   SchemaBuilder,
+  SchemaEnrichment,
   SchemaValidationError,
   SymmetricLensHandle,
   TheoryBuilder,