@panproto/core 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -2060,6 +2060,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.
    *
@@ -2365,6 +2369,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. */
@@ -2503,12 +3036,14 @@ exports.CompatReport = CompatReport;
 exports.CompiledMigration = CompiledMigration;
 exports.DataSetHandle = DataSetHandle;
 exports.ExistenceCheckError = ExistenceCheckError;
+exports.ExprBuilder = ExprBuilder;
 exports.FullDiffReport = FullDiffReport;
 exports.GRAPHQL_SPEC = GRAPHQL_SPEC;
 exports.Instance = Instance;
 exports.IoRegistry = IoRegistry;
 exports.JSON_SCHEMA_SPEC = JSON_SCHEMA_SPEC;
 exports.LensHandle = LensHandle;
+exports.MigrationAnalysis = MigrationAnalysis;
 exports.MigrationBuilder = MigrationBuilder;
 exports.MigrationError = MigrationError;
 exports.PROTOBUF_SPEC = PROTOBUF_SPEC;
@@ -2520,6 +3055,7 @@ exports.ProtolensChainHandle = ProtolensChainHandle;
 exports.Repository = Repository;
 exports.SQL_SPEC = SQL_SPEC;
 exports.SchemaBuilder = SchemaBuilder;
+exports.SchemaEnrichment = SchemaEnrichment;
 exports.SchemaValidationError = SchemaValidationError;
 exports.SymmetricLensHandle = SymmetricLensHandle;
 exports.TheoryBuilder = TheoryBuilder;