@panproto/core 0.5.1 → 0.7.0

package/dist/index.cjs

@@ -71,7 +71,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,
@@ -97,7 +111,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) {
@@ -171,30 +194,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;
@@ -207,6 +412,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.
    *
@@ -324,40 +576,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 {
@@ -1703,6 +1989,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;
@@ -1932,6 +2282,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.
    *
@@ -2065,11 +2485,23 @@ 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 }
+    );
+  }
+}
 exports.ATPROTO_SPEC = ATPROTO_SPEC;
 exports.BUILTIN_PROTOCOLS = BUILTIN_PROTOCOLS;
 exports.BuiltSchema = BuiltSchema;
 exports.CompatReport = CompatReport;
 exports.CompiledMigration = CompiledMigration;
+exports.DataSetHandle = DataSetHandle;
 exports.ExistenceCheckError = ExistenceCheckError;
 exports.FullDiffReport = FullDiffReport;
 exports.GRAPHQL_SPEC = GRAPHQL_SPEC;
@@ -2084,27 +2516,21 @@ exports.PROTOCOL_CATEGORIES = PROTOCOL_CATEGORIES;
 exports.Panproto = Panproto;
 exports.PanprotoError = PanprotoError;
 exports.Protocol = Protocol;
+exports.ProtolensChainHandle = ProtolensChainHandle;
 exports.Repository = Repository;
 exports.SQL_SPEC = SQL_SPEC;
 exports.SchemaBuilder = SchemaBuilder;
 exports.SchemaValidationError = SchemaValidationError;
+exports.SymmetricLensHandle = SymmetricLensHandle;
 exports.TheoryBuilder = TheoryBuilder;
 exports.TheoryHandle = TheoryHandle;
 exports.ValidationResult = ValidationResult;
 exports.WasmError = WasmError;
-exports.addField = addField;
 exports.checkMorphism = checkMorphism;
-exports.coerceType = coerceType;
 exports.colimit = colimit;
-exports.compose = compose;
 exports.createTheory = createTheory;
-exports.fromCombinators = fromCombinators;
+exports.factorizeMorphism = factorizeMorphism;
 exports.getBuiltinProtocol = getBuiltinProtocol;
 exports.getProtocolNames = getProtocolNames;
-exports.hoistField = hoistField;
 exports.migrateModel = migrateModel;
-exports.pipeline = pipeline;
-exports.removeField = removeField;
-exports.renameField = renameField;
-exports.wrapInObject = wrapInObject;
 //# sourceMappingURL=index.cjs.map