@panproto/core 0.6.0 → 0.8.0

package/dist/index.js

@@ -68,7 +68,21 @@ async function loadWasm(input) {
       get_json: glue.get_json,
       put_json: glue.put_json,
       instance_element_count: glue.instance_element_count,
-      lens_from_combinators: glue.lens_from_combinators,
+      auto_generate_protolens: glue.auto_generate_protolens,
+      instantiate_protolens: glue.instantiate_protolens,
+      protolens_complement_spec: glue.protolens_complement_spec,
+      protolens_from_diff: glue.protolens_from_diff,
+      protolens_compose: glue.protolens_compose,
+      protolens_chain_to_json: glue.protolens_chain_to_json,
+      factorize_morphism: glue.factorize_morphism,
+      symmetric_lens_from_schemas: glue.symmetric_lens_from_schemas,
+      symmetric_lens_sync: glue.symmetric_lens_sync,
+      apply_protolens_step: glue.apply_protolens_step,
+      protolens_from_json: glue.protolens_from_json,
+      protolens_fuse: glue.protolens_fuse,
+      protolens_lift: glue.protolens_lift,
+      protolens_check_applicability: glue.protolens_check_applicability,
+      protolens_fleet: glue.protolens_fleet,
       check_lens_laws: glue.check_lens_laws,
       check_get_put: glue.check_get_put,
       check_put_get: glue.check_put_get,
@@ -94,7 +108,16 @@ async function loadWasm(input) {
       vcs_merge: glue.vcs_merge,
       vcs_stash: glue.vcs_stash,
       vcs_stash_pop: glue.vcs_stash_pop,
-      vcs_blame: glue.vcs_blame
+      vcs_blame: glue.vcs_blame,
+      // Phase 7: Data versioning
+      store_dataset: glue.store_dataset,
+      get_dataset: glue.get_dataset,
+      migrate_dataset_forward: glue.migrate_dataset_forward,
+      migrate_dataset_backward: glue.migrate_dataset_backward,
+      check_dataset_staleness: glue.check_dataset_staleness,
+      store_protocol_definition: glue.store_protocol_definition,
+      get_protocol_definition: glue.get_protocol_definition,
+      get_migration_complement: glue.get_migration_complement
     };
     const memory = initOutput.memory;
     if (!memory) {
@@ -168,30 +191,212 @@ function packMigrationMapping(mapping) {
     hyper_resolver: []
   });
 }
-function renameField(oldName, newName) {
-  return { type: "rename-field", old: oldName, new: newName };
-}
-function addField(name, vertexKind, defaultValue) {
-  return { type: "add-field", name, vertexKind, default: defaultValue };
-}
-function removeField(name) {
-  return { type: "remove-field", name };
-}
-function wrapInObject(fieldName) {
-  return { type: "wrap-in-object", fieldName };
-}
-function hoistField(host, field) {
-  return { type: "hoist-field", host, field };
-}
-function coerceType(fromKind, toKind) {
-  return { type: "coerce-type", fromKind, toKind };
-}
-function compose(first, second) {
-  return { type: "compose", first, second };
-}
-function pipeline(combinators) {
-  const [first, ...rest] = combinators;
-  return rest.reduce((acc, c) => compose(acc, c), first);
+class ProtolensChainHandle {
+  #handle;
+  #wasm;
+  constructor(handle, wasm) {
+    this.#handle = handle;
+    this.#wasm = wasm;
+  }
+  /** The underlying WASM handle. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /**
+   * Auto-generate a protolens chain between two schemas.
+   *
+   * @param schema1 - The source schema
+   * @param schema2 - The target schema
+   * @param wasm - The WASM module
+   * @returns A ProtolensChainHandle wrapping the generated chain
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  static autoGenerate(schema1, schema2, wasm) {
+    try {
+      const rawHandle = wasm.exports.auto_generate_protolens(schema1._handle.id, schema2._handle.id);
+      return new ProtolensChainHandle(createHandle(rawHandle, wasm), wasm);
+    } catch (error) {
+      throw new WasmError(
+        `auto_generate_protolens failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Instantiate this protolens chain against a concrete schema.
+   *
+   * @param schema - The schema to instantiate against
+   * @returns A LensHandle for the instantiated lens
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  instantiate(schema) {
+    try {
+      const rawHandle = this.#wasm.exports.instantiate_protolens(this.#handle.id, schema._handle.id);
+      return new LensHandle(createHandle(rawHandle, this.#wasm), this.#wasm);
+    } catch (error) {
+      throw new WasmError(
+        `instantiate_protolens failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get the complement specification for instantiation against a schema.
+   *
+   * @param schema - The schema to check requirements against
+   * @returns The complement spec describing defaults and captured data
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  requirements(schema) {
+    try {
+      const bytes = this.#wasm.exports.protolens_complement_spec(this.#handle.id, schema._handle.id);
+      return unpackFromWasm(bytes);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_complement_spec failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Compose this chain with another protolens chain.
+   *
+   * @param other - The chain to compose with (applied second)
+   * @returns A new ProtolensChainHandle for the composed chain
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  compose(other) {
+    try {
+      const rawHandle = this.#wasm.exports.protolens_compose(this.#handle.id, other.#handle.id);
+      return new ProtolensChainHandle(createHandle(rawHandle, this.#wasm), this.#wasm);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_compose failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Serialize this chain to a JSON string.
+   *
+   * @returns A JSON representation of the chain
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  toJson() {
+    try {
+      const bytes = this.#wasm.exports.protolens_chain_to_json(this.#handle.id);
+      return new TextDecoder().decode(bytes);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_chain_to_json failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Deserialize a protolens chain from JSON via WASM.
+   *
+   * @param json - JSON string representing a protolens chain
+   * @param wasm - The WASM module
+   * @returns A ProtolensChainHandle wrapping the deserialized chain
+   * @throws {@link WasmError} if the WASM call fails or JSON is invalid
+   */
+  static fromJson(json, wasm) {
+    try {
+      const jsonBytes = new TextEncoder().encode(json);
+      const rawHandle = wasm.exports.protolens_from_json(jsonBytes);
+      return new ProtolensChainHandle(createHandle(rawHandle, wasm), wasm);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_from_json failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Fuse this chain into a single protolens step.
+   *
+   * Composes all steps into a single step with a composite complement,
+   * avoiding intermediate schema materialization.
+   *
+   * @returns A new ProtolensChainHandle containing the fused step
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  fuse() {
+    try {
+      const rawHandle = this.#wasm.exports.protolens_fuse(this.#handle.id);
+      return new ProtolensChainHandle(createHandle(rawHandle, this.#wasm), this.#wasm);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_fuse failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Check whether this chain can be instantiated at a given schema.
+   *
+   * @param schema - The schema to check against
+   * @returns An object with `applicable` boolean and `reasons` array
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  checkApplicability(schema) {
+    try {
+      const bytes = this.#wasm.exports.protolens_check_applicability(this.#handle.id, schema._handle.id);
+      return unpackFromWasm(bytes);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_check_applicability failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Lift this chain along a theory morphism.
+   *
+   * Given a morphism between theories, produces a new chain that operates
+   * on schemas of the codomain theory instead of the domain theory.
+   *
+   * @param morphismBytes - MessagePack-encoded theory morphism
+   * @returns A new ProtolensChainHandle for the lifted chain
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  lift(morphismBytes) {
+    try {
+      const rawHandle = this.#wasm.exports.protolens_lift(this.#handle.id, morphismBytes);
+      return new ProtolensChainHandle(createHandle(rawHandle, this.#wasm), this.#wasm);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_lift failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Apply this chain to a fleet of schemas.
+   *
+   * Checks applicability and instantiates the chain against each schema.
+   *
+   * @param schemas - Array of schema handles to apply the chain to
+   * @returns Fleet result with applied/skipped schema names and reasons
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  applyToFleet(schemas) {
+    try {
+      const handles = new Uint32Array(schemas.map((s) => s._handle.id));
+      const bytes = this.#wasm.exports.protolens_fleet(this.#handle.id, handles);
+      return unpackFromWasm(bytes);
+    } catch (error) {
+      throw new WasmError(
+        `protolens_fleet failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /** Release the underlying WASM resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
 }
 class LensHandle {
   #handle;
@@ -204,6 +409,53 @@ class LensHandle {
   get _handle() {
     return this.#handle;
   }
+  /**
+   * Auto-generate a lens between two schemas.
+   *
+   * Generates a protolens chain and immediately instantiates it.
+   *
+   * @param schema1 - The source schema
+   * @param schema2 - The target schema
+   * @param wasm - The WASM module
+   * @returns A LensHandle wrapping the generated lens
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  static autoGenerate(schema1, schema2, wasm) {
+    try {
+      const rawHandle = wasm.exports.auto_generate_protolens(schema1._handle.id, schema2._handle.id);
+      const chainHandle = createHandle(rawHandle, wasm);
+      const lensRaw = wasm.exports.instantiate_protolens(chainHandle.id, schema1._handle.id);
+      chainHandle[Symbol.dispose]();
+      const handle = createHandle(lensRaw, wasm);
+      return new LensHandle(handle, wasm);
+    } catch (error) {
+      throw new WasmError(
+        `autoGenerate failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Create a lens by instantiating a protolens chain against a schema.
+   *
+   * @param chain - The protolens chain to instantiate
+   * @param schema - The schema to instantiate against
+   * @param wasm - The WASM module
+   * @returns A LensHandle wrapping the instantiated lens
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  static fromChain(chain, schema, wasm) {
+    try {
+      const rawHandle = wasm.exports.instantiate_protolens(chain._handle.id, schema._handle.id);
+      const handle = createHandle(rawHandle, wasm);
+      return new LensHandle(handle, wasm);
+    } catch (error) {
+      throw new WasmError(
+        `fromChain failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
   /**
    * Forward projection: extract the view from a record.
    *
@@ -321,40 +573,74 @@ class LensHandle {
     this.#handle[Symbol.dispose]();
   }
 }
-function fromCombinators(schema, protocol, wasm, ...combinators) {
-  const wireCombs = combinators.map(combinatorToWire);
-  const combBytes = packToWasm(wireCombs);
-  try {
-    const rawHandle = wasm.exports.lens_from_combinators(
-      schema._handle.id,
-      protocol._handle.id,
-      combBytes
-    );
-    const handle = createHandle(rawHandle, wasm);
-    return new LensHandle(handle, wasm);
-  } catch (error) {
-    throw new WasmError(
-      `lens_from_combinators failed: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error }
-    );
+class SymmetricLensHandle {
+  #handle;
+  #wasm;
+  constructor(handle, wasm) {
+    this.#handle = handle;
+    this.#wasm = wasm;
   }
-}
-function combinatorToWire(combinator) {
-  switch (combinator.type) {
-    case "rename-field":
-      return { RenameField: { old: combinator.old, new: combinator.new } };
-    case "add-field":
-      return { AddField: { name: combinator.name, vertex_kind: combinator.vertexKind, default: combinator.default } };
-    case "remove-field":
-      return { RemoveField: { name: combinator.name } };
-    case "wrap-in-object":
-      return { WrapInObject: { field_name: combinator.fieldName } };
-    case "hoist-field":
-      return { HoistField: { host: combinator.host, field: combinator.field } };
-    case "coerce-type":
-      return { CoerceType: { from_kind: combinator.fromKind, to_kind: combinator.toKind } };
-    case "compose":
-      return { Compose: [combinatorToWire(combinator.first), combinatorToWire(combinator.second)] };
+  /**
+   * Create a symmetric lens between two schemas.
+   *
+   * @param schema1 - The left schema
+   * @param schema2 - The right schema
+   * @param wasm - The WASM module
+   * @returns A SymmetricLensHandle for bidirectional sync
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  static fromSchemas(schema1, schema2, wasm) {
+    try {
+      const rawHandle = wasm.exports.symmetric_lens_from_schemas(schema1._handle.id, schema2._handle.id);
+      return new SymmetricLensHandle(createHandle(rawHandle, wasm), wasm);
+    } catch (error) {
+      throw new WasmError(
+        `symmetric_lens_from_schemas failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Synchronize left view to right view.
+   *
+   * @param leftView - MessagePack-encoded left view data
+   * @param leftComplement - Opaque complement bytes from a prior sync
+   * @returns The synchronized right view and updated complement
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  syncLeftToRight(leftView, leftComplement) {
+    try {
+      const bytes = this.#wasm.exports.symmetric_lens_sync(this.#handle.id, leftView, leftComplement, 0);
+      return unpackFromWasm(bytes);
+    } catch (error) {
+      throw new WasmError(
+        `symmetric_lens_sync (left-to-right) failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Synchronize right view to left view.
+   *
+   * @param rightView - MessagePack-encoded right view data
+   * @param rightComplement - Opaque complement bytes from a prior sync
+   * @returns The synchronized left view and updated complement
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  syncRightToLeft(rightView, rightComplement) {
+    try {
+      const bytes = this.#wasm.exports.symmetric_lens_sync(this.#handle.id, rightView, rightComplement, 1);
+      return unpackFromWasm(bytes);
+    } catch (error) {
+      throw new WasmError(
+        `symmetric_lens_sync (right-to-left) failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /** Release the underlying WASM resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
   }
 }
 class FullDiffReport {
@@ -1700,6 +1986,70 @@ class Repository {
     this.#handle[Symbol.dispose]();
   }
 }
+class DataSetHandle {
+  #handle;
+  #wasm;
+  constructor(handle, wasm) {
+    this.#handle = handle;
+    this.#wasm = wasm;
+  }
+  /** The WASM handle for this data set. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /** Store a data set from a JavaScript object, bound to a schema. */
+  static fromData(data, schema, wasm) {
+    const jsonBytes = new TextEncoder().encode(JSON.stringify(data));
+    const rawHandle = wasm.exports.store_dataset(schema._handle.id, jsonBytes);
+    return new DataSetHandle(createHandle(rawHandle, wasm), wasm);
+  }
+  /** Retrieve the data as MessagePack-encoded bytes. */
+  getData() {
+    const bytes = this.#wasm.exports.get_dataset(this.#handle.id);
+    return unpackFromWasm(bytes);
+  }
+  /** Migrate this data set forward to a new schema. */
+  migrateForward(srcSchema, tgtSchema) {
+    const bytes = this.#wasm.exports.migrate_dataset_forward(
+      this.#handle.id,
+      srcSchema._handle.id,
+      tgtSchema._handle.id
+    );
+    const result = unpackFromWasm(bytes);
+    const complementBytes = this.#wasm.exports.get_dataset(result.complement_handle);
+    this.#wasm.exports.free_handle(result.complement_handle);
+    return {
+      data: new DataSetHandle(createHandle(result.data_handle, this.#wasm), this.#wasm),
+      complement: new Uint8Array(complementBytes)
+    };
+  }
+  /** Migrate this data set backward using a complement. */
+  migrateBackward(complement, srcSchema, tgtSchema) {
+    const rawHandle = this.#wasm.exports.migrate_dataset_backward(
+      this.#handle.id,
+      complement,
+      srcSchema._handle.id,
+      tgtSchema._handle.id
+    );
+    return new DataSetHandle(createHandle(rawHandle, this.#wasm), this.#wasm);
+  }
+  /** Check if this data set is stale relative to a schema. */
+  isStale(schema) {
+    const bytes = this.#wasm.exports.check_dataset_staleness(
+      this.#handle.id,
+      schema._handle.id
+    );
+    const raw = unpackFromWasm(bytes);
+    return {
+      stale: raw.stale,
+      dataSchemaId: raw.data_schema_id,
+      targetSchemaId: raw.target_schema_id
+    };
+  }
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
+}
 class Panproto {
   #wasm;
   #protocols;
@@ -1707,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.
    *
@@ -1929,6 +2283,76 @@ class Panproto {
   initRepo(protocolName) {
     return Repository.init(protocolName, this.#wasm);
   }
+  /**
+   * Convert data from one schema to another using an auto-generated lens.
+   *
+   * This is a convenience method that generates a protolens, applies the
+   * forward projection, and disposes the lens automatically.
+   *
+   * @param data - The input data (Uint8Array of MessagePack, or a plain object)
+   * @param opts - Conversion options specifying source and target schemas
+   * @returns The converted data
+   * @throws {@link WasmError} if lens generation or conversion fails
+   */
+  async convert(data, opts) {
+    const lens = LensHandle.autoGenerate(opts.from, opts.to, this.#wasm);
+    try {
+      const input = data instanceof Uint8Array ? data : packToWasm(data);
+      const result = lens.get(input);
+      return result.view;
+    } finally {
+      lens[Symbol.dispose]();
+    }
+  }
+  /**
+   * Create an auto-generated lens between two schemas.
+   *
+   * @param from - The source schema
+   * @param to - The target schema
+   * @returns A LensHandle for the generated lens
+   * @throws {@link WasmError} if lens generation fails
+   */
+  lens(from, to) {
+    return LensHandle.autoGenerate(from, to, this.#wasm);
+  }
+  /**
+   * Create a protolens chain between two schemas.
+   *
+   * The returned chain is schema-independent and can be instantiated
+   * against different concrete schemas.
+   *
+   * @param from - The source schema
+   * @param to - The target schema
+   * @returns A ProtolensChainHandle for the generated chain
+   * @throws {@link WasmError} if chain generation fails
+   */
+  protolensChain(from, to) {
+    return ProtolensChainHandle.autoGenerate(from, to, this.#wasm);
+  }
+  /**
+   * Store and track a data set against a schema.
+   *
+   * @param data - The data to store (array of records or a single object)
+   * @param schema - The schema this data conforms to
+   * @returns A disposable DataSetHandle
+   */
+  dataSet(data, schema) {
+    return DataSetHandle.fromData(data, schema, this.#wasm);
+  }
+  /**
+   * Migrate data forward between two schemas.
+   *
+   * Auto-generates a lens and migrates each record, returning the
+   * migrated data and a complement for backward migration.
+   *
+   * @param data - The data set to migrate
+   * @param from - The source schema
+   * @param to - The target schema
+   * @returns The migration result with new data and complement
+   */
+  migrateData(data, from, to) {
+    return data.migrateForward(from, to);
+  }
   /**
    * Release all WASM resources held by this instance.
    *
@@ -1942,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. */
@@ -2062,19 +3015,33 @@ function migrateModel(sortInterp, morphism, wasm) {
   const resultBytes = wasm.exports.migrate_model(modelBytes, morphBytes);
   return unpackFromWasm(resultBytes);
 }
+function factorizeMorphism(morphismBytes, domain, codomain, wasm) {
+  try {
+    const bytes = wasm.exports.factorize_morphism(morphismBytes, domain._handle.id, codomain._handle.id);
+    return unpackFromWasm(bytes);
+  } catch (error) {
+    throw new WasmError(
+      `factorize_morphism failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+}
 export {
   ATPROTO_SPEC,
   BUILTIN_PROTOCOLS,
   BuiltSchema,
   CompatReport,
   CompiledMigration,
+  DataSetHandle,
   ExistenceCheckError,
+  ExprBuilder,
   FullDiffReport,
   GRAPHQL_SPEC,
   Instance,
   IoRegistry,
   JSON_SCHEMA_SPEC,
   LensHandle,
+  MigrationAnalysis,
   MigrationBuilder,
   MigrationError,
   PROTOBUF_SPEC,
@@ -2082,28 +3049,23 @@ export {
   Panproto,
   PanprotoError,
   Protocol,
+  ProtolensChainHandle,
   Repository,
   SQL_SPEC,
   SchemaBuilder,
+  SchemaEnrichment,
   SchemaValidationError,
+  SymmetricLensHandle,
   TheoryBuilder,
   TheoryHandle,
   ValidationResult,
   WasmError,
-  addField,
   checkMorphism,
-  coerceType,
   colimit,
-  compose,
   createTheory,
-  fromCombinators,
+  factorizeMorphism,
   getBuiltinProtocol,
   getProtocolNames,
-  hoistField,
-  migrateModel,
-  pipeline,
-  removeField,
-  renameField,
-  wrapInObject
+  migrateModel
 };
 //# sourceMappingURL=index.js.map