@panproto/core 0.1.0

package/dist/index.js

@@ -0,0 +1,944 @@
+import { encode, decode } from "@msgpack/msgpack";
+class PanprotoError extends Error {
+  name = "PanprotoError";
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+class WasmError extends PanprotoError {
+  name = "WasmError";
+}
+class SchemaValidationError extends PanprotoError {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+  }
+  name = "SchemaValidationError";
+}
+class MigrationError extends PanprotoError {
+  name = "MigrationError";
+}
+class ExistenceCheckError extends PanprotoError {
+  constructor(message, report) {
+    super(message);
+    this.report = report;
+  }
+  name = "ExistenceCheckError";
+}
+const DEFAULT_WASM_URL = new URL("./panproto_wasm_bg.wasm", import.meta.url);
+async function loadWasm(url) {
+  const wasmUrl = url ?? DEFAULT_WASM_URL;
+  try {
+    const response = typeof wasmUrl === "string" ? await fetch(wasmUrl) : await fetch(wasmUrl);
+    const { instance } = await WebAssembly.instantiateStreaming(response);
+    const exports$1 = instance.exports;
+    const memory = instance.exports["memory"];
+    if (!memory) {
+      throw new WasmError("WASM module missing memory export");
+    }
+    return { exports: exports$1, memory };
+  } catch (error) {
+    if (error instanceof WasmError) throw error;
+    throw new WasmError(
+      `Failed to load WASM module from ${String(wasmUrl)}`,
+      { cause: error }
+    );
+  }
+}
+const leakedHandleRegistry = new FinalizationRegistry((info) => {
+  try {
+    info.freeHandle(info.handle);
+  } catch {
+  }
+});
+class WasmHandle {
+  #handle;
+  #disposed = false;
+  #freeHandle;
+  constructor(handle, freeHandle) {
+    this.#handle = handle;
+    this.#freeHandle = freeHandle;
+    leakedHandleRegistry.register(this, { handle, freeHandle }, this);
+  }
+  /** The raw WASM handle id. Only for internal use within the SDK. */
+  get id() {
+    if (this.#disposed) {
+      throw new WasmError("Attempted to use a disposed handle");
+    }
+    return this.#handle;
+  }
+  /** Whether this handle has been disposed. */
+  get disposed() {
+    return this.#disposed;
+  }
+  /** Release the underlying WASM resource. */
+  [Symbol.dispose]() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    leakedHandleRegistry.unregister(this);
+    try {
+      this.#freeHandle(this.#handle);
+    } catch {
+    }
+  }
+}
+function createHandle(rawHandle, wasm) {
+  return new WasmHandle(rawHandle, (h) => wasm.exports.free_handle(h));
+}
+function packToWasm(value) {
+  return encode(value);
+}
+function unpackFromWasm(bytes) {
+  return decode(bytes);
+}
+function packSchemaOps(ops) {
+  return encode(ops);
+}
+function packMigrationMapping(mapping) {
+  return encode(mapping);
+}
+class SchemaBuilder {
+  #protocolName;
+  #protocolHandle;
+  #wasm;
+  #ops;
+  #vertices;
+  #edges;
+  #hyperEdges;
+  #constraints;
+  #required;
+  constructor(protocolName, protocolHandle, wasm, ops = [], vertices = /* @__PURE__ */ new Map(), edges = [], hyperEdges = /* @__PURE__ */ new Map(), constraints = /* @__PURE__ */ new Map(), required = /* @__PURE__ */ new Map()) {
+    this.#protocolName = protocolName;
+    this.#protocolHandle = protocolHandle;
+    this.#wasm = wasm;
+    this.#ops = ops;
+    this.#vertices = vertices;
+    this.#edges = edges;
+    this.#hyperEdges = hyperEdges;
+    this.#constraints = constraints;
+    this.#required = required;
+  }
+  /**
+   * Add a vertex to the schema.
+   *
+   * @param id - Unique vertex identifier
+   * @param kind - Vertex kind (e.g., 'record', 'object', 'string')
+   * @param options - Optional vertex configuration (nsid, etc.)
+   * @returns A new builder with the vertex added
+   * @throws {@link SchemaValidationError} if vertex id is already in use
+   */
+  vertex(id, kind, options) {
+    if (this.#vertices.has(id)) {
+      throw new SchemaValidationError(
+        `Vertex "${id}" already exists in schema`,
+        [`Duplicate vertex id: ${id}`]
+      );
+    }
+    const vertex = {
+      id,
+      kind,
+      nsid: options?.nsid
+    };
+    const op = {
+      op: "vertex",
+      id,
+      kind,
+      nsid: options?.nsid ?? null
+    };
+    const newVertices = new Map(this.#vertices);
+    newVertices.set(id, vertex);
+    return new SchemaBuilder(
+      this.#protocolName,
+      this.#protocolHandle,
+      this.#wasm,
+      [...this.#ops, op],
+      newVertices,
+      this.#edges,
+      this.#hyperEdges,
+      this.#constraints,
+      this.#required
+    );
+  }
+  /**
+   * Add a directed edge to the schema.
+   *
+   * @param src - Source vertex id
+   * @param tgt - Target vertex id
+   * @param kind - Edge kind (e.g., 'record-schema', 'prop')
+   * @param options - Optional edge configuration (name, etc.)
+   * @returns A new builder with the edge added
+   * @throws {@link SchemaValidationError} if source or target vertex does not exist
+   */
+  edge(src, tgt, kind, options) {
+    if (!this.#vertices.has(src)) {
+      throw new SchemaValidationError(
+        `Edge source "${src}" does not exist`,
+        [`Unknown source vertex: ${src}`]
+      );
+    }
+    if (!this.#vertices.has(tgt)) {
+      throw new SchemaValidationError(
+        `Edge target "${tgt}" does not exist`,
+        [`Unknown target vertex: ${tgt}`]
+      );
+    }
+    const edge = {
+      src,
+      tgt,
+      kind,
+      name: options?.name
+    };
+    const op = {
+      op: "edge",
+      src,
+      tgt,
+      kind,
+      name: options?.name ?? null
+    };
+    return new SchemaBuilder(
+      this.#protocolName,
+      this.#protocolHandle,
+      this.#wasm,
+      [...this.#ops, op],
+      this.#vertices,
+      [...this.#edges, edge],
+      this.#hyperEdges,
+      this.#constraints,
+      this.#required
+    );
+  }
+  /**
+   * Add a hyperedge to the schema.
+   *
+   * Only valid if the protocol's schema theory includes ThHypergraph.
+   *
+   * @param id - Unique hyperedge identifier
+   * @param kind - Hyperedge kind
+   * @param signature - Label-to-vertex mapping
+   * @param parentLabel - The label identifying the parent in the signature
+   * @returns A new builder with the hyperedge added
+   */
+  hyperEdge(id, kind, signature, parentLabel) {
+    const he = { id, kind, signature, parentLabel };
+    const op = {
+      op: "hyper_edge",
+      id,
+      kind,
+      signature,
+      parent: parentLabel
+    };
+    const newHyperEdges = new Map(this.#hyperEdges);
+    newHyperEdges.set(id, he);
+    return new SchemaBuilder(
+      this.#protocolName,
+      this.#protocolHandle,
+      this.#wasm,
+      [...this.#ops, op],
+      this.#vertices,
+      this.#edges,
+      newHyperEdges,
+      this.#constraints,
+      this.#required
+    );
+  }
+  /**
+   * Add a constraint to a vertex.
+   *
+   * @param vertexId - The vertex to constrain
+   * @param sort - Constraint sort (e.g., 'maxLength')
+   * @param value - Constraint value
+   * @returns A new builder with the constraint added
+   */
+  constraint(vertexId, sort, value) {
+    const c = { sort, value };
+    const op = {
+      op: "constraint",
+      vertex: vertexId,
+      sort,
+      value
+    };
+    const existing = this.#constraints.get(vertexId) ?? [];
+    const newConstraints = new Map(this.#constraints);
+    newConstraints.set(vertexId, [...existing, c]);
+    return new SchemaBuilder(
+      this.#protocolName,
+      this.#protocolHandle,
+      this.#wasm,
+      [...this.#ops, op],
+      this.#vertices,
+      this.#edges,
+      this.#hyperEdges,
+      newConstraints,
+      this.#required
+    );
+  }
+  /**
+   * Mark edges as required for a vertex.
+   *
+   * @param vertexId - The vertex with required edges
+   * @param edges - The edges that are required
+   * @returns A new builder with the requirement added
+   */
+  required(vertexId, edges) {
+    const op = {
+      op: "required",
+      vertex: vertexId,
+      edges: edges.map((e) => ({
+        src: e.src,
+        tgt: e.tgt,
+        kind: e.kind,
+        name: e.name ?? null
+      }))
+    };
+    const existing = this.#required.get(vertexId) ?? [];
+    const newRequired = new Map(this.#required);
+    newRequired.set(vertexId, [...existing, ...edges]);
+    return new SchemaBuilder(
+      this.#protocolName,
+      this.#protocolHandle,
+      this.#wasm,
+      [...this.#ops, op],
+      this.#vertices,
+      this.#edges,
+      this.#hyperEdges,
+      this.#constraints,
+      newRequired
+    );
+  }
+  /**
+   * Validate and build the schema.
+   *
+   * Sends all accumulated operations to WASM for validation and construction.
+   * Returns a `BuiltSchema` that holds the WASM handle and local data.
+   *
+   * @returns The validated, built schema
+   * @throws {@link SchemaValidationError} if the schema is invalid
+   */
+  build() {
+    const opsBytes = packSchemaOps([...this.#ops]);
+    const rawHandle = this.#wasm.exports.build_schema(
+      this.#protocolHandle.id,
+      opsBytes
+    );
+    const handle = createHandle(rawHandle, this.#wasm);
+    const data = {
+      protocol: this.#protocolName,
+      vertices: Object.fromEntries(this.#vertices),
+      edges: [...this.#edges],
+      hyperEdges: Object.fromEntries(this.#hyperEdges),
+      constraints: Object.fromEntries(
+        Array.from(this.#constraints.entries()).map(([k, v]) => [k, [...v]])
+      ),
+      required: Object.fromEntries(
+        Array.from(this.#required.entries()).map(([k, v]) => [k, [...v]])
+      )
+    };
+    return new BuiltSchema(handle, data, this.#wasm);
+  }
+}
+class BuiltSchema {
+  #handle;
+  #data;
+  #wasm;
+  constructor(handle, data, wasm) {
+    this.#handle = handle;
+    this.#data = data;
+    this.#wasm = wasm;
+  }
+  /** The WASM handle for this schema. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /** The WASM module reference. Internal use only. */
+  get _wasm() {
+    return this.#wasm;
+  }
+  /** The schema data (vertices, edges, constraints, etc.). */
+  get data() {
+    return this.#data;
+  }
+  /** The protocol name this schema belongs to. */
+  get protocol() {
+    return this.#data.protocol;
+  }
+  /** All vertices in the schema. */
+  get vertices() {
+    return this.#data.vertices;
+  }
+  /** All edges in the schema. */
+  get edges() {
+    return this.#data.edges;
+  }
+  /** Release the WASM-side schema resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
+}
+class Protocol {
+  #handle;
+  #spec;
+  #wasm;
+  constructor(handle, spec, wasm) {
+    this.#handle = handle;
+    this.#spec = spec;
+    this.#wasm = wasm;
+  }
+  /** The protocol name. */
+  get name() {
+    return this.#spec.name;
+  }
+  /** The full protocol specification. */
+  get spec() {
+    return this.#spec;
+  }
+  /** The WASM handle. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /**
+   * Start building a schema within this protocol.
+   *
+   * @returns A new `SchemaBuilder` bound to this protocol
+   */
+  schema() {
+    return new SchemaBuilder(this.#spec.name, this.#handle, this.#wasm);
+  }
+  /** Release the WASM-side protocol resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
+}
+function defineProtocol(spec, wasm) {
+  const wireSpec = {
+    name: spec.name,
+    schema_theory: spec.schemaTheory,
+    instance_theory: spec.instanceTheory,
+    edge_rules: spec.edgeRules.map((r) => ({
+      edge_kind: r.edgeKind,
+      src_kinds: [...r.srcKinds],
+      tgt_kinds: [...r.tgtKinds]
+    })),
+    obj_kinds: [...spec.objKinds],
+    constraint_sorts: [...spec.constraintSorts]
+  };
+  try {
+    const bytes = packToWasm(wireSpec);
+    const rawHandle = wasm.exports.define_protocol(bytes);
+    const handle = createHandle(rawHandle, wasm);
+    return new Protocol(handle, spec, wasm);
+  } catch (error) {
+    throw new PanprotoError(
+      `Failed to define protocol "${spec.name}": ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+}
+const ATPROTO_SPEC = {
+  name: "atproto",
+  schemaTheory: "ThConstrainedMultiGraph",
+  instanceTheory: "ThWTypeMeta",
+  edgeRules: [
+    { edgeKind: "record-schema", srcKinds: ["record"], tgtKinds: ["object"] },
+    { edgeKind: "prop", srcKinds: ["object"], tgtKinds: [] },
+    { edgeKind: "item", srcKinds: ["array"], tgtKinds: [] },
+    { edgeKind: "variant", srcKinds: ["union"], tgtKinds: [] },
+    { edgeKind: "ref", srcKinds: [], tgtKinds: ["record"] }
+  ],
+  objKinds: ["record", "object"],
+  constraintSorts: ["maxLength", "minLength", "maxGraphemes", "minGraphemes", "format"]
+};
+const SQL_SPEC = {
+  name: "sql",
+  schemaTheory: "ThConstrainedHypergraph",
+  instanceTheory: "ThFunctor",
+  edgeRules: [
+    { edgeKind: "column", srcKinds: ["table"], tgtKinds: ["type"] },
+    { edgeKind: "fk", srcKinds: ["table"], tgtKinds: ["table"] },
+    { edgeKind: "pk", srcKinds: ["table"], tgtKinds: ["column"] }
+  ],
+  objKinds: ["table"],
+  constraintSorts: ["nullable", "unique", "check", "default"]
+};
+const PROTOBUF_SPEC = {
+  name: "protobuf",
+  schemaTheory: "ThConstrainedGraph",
+  instanceTheory: "ThWType",
+  edgeRules: [
+    { edgeKind: "field", srcKinds: ["message"], tgtKinds: [] },
+    { edgeKind: "nested", srcKinds: ["message"], tgtKinds: ["message", "enum"] },
+    { edgeKind: "value", srcKinds: ["enum"], tgtKinds: ["enum-value"] }
+  ],
+  objKinds: ["message"],
+  constraintSorts: ["field-number", "repeated", "optional", "map-key", "map-value"]
+};
+const GRAPHQL_SPEC = {
+  name: "graphql",
+  schemaTheory: "ThConstrainedGraph",
+  instanceTheory: "ThWType",
+  edgeRules: [
+    { edgeKind: "field", srcKinds: ["type", "input"], tgtKinds: [] },
+    { edgeKind: "implements", srcKinds: ["type"], tgtKinds: ["interface"] },
+    { edgeKind: "member", srcKinds: ["union"], tgtKinds: ["type"] },
+    { edgeKind: "value", srcKinds: ["enum"], tgtKinds: ["enum-value"] }
+  ],
+  objKinds: ["type", "input"],
+  constraintSorts: ["non-null", "list", "deprecated"]
+};
+const JSON_SCHEMA_SPEC = {
+  name: "json-schema",
+  schemaTheory: "ThConstrainedGraph",
+  instanceTheory: "ThWType",
+  edgeRules: [
+    { edgeKind: "property", srcKinds: ["object"], tgtKinds: [] },
+    { edgeKind: "item", srcKinds: ["array"], tgtKinds: [] },
+    { edgeKind: "variant", srcKinds: ["oneOf", "anyOf"], tgtKinds: [] }
+  ],
+  objKinds: ["object"],
+  constraintSorts: ["minLength", "maxLength", "minimum", "maximum", "pattern", "format", "required"]
+};
+const BUILTIN_PROTOCOLS = /* @__PURE__ */ new Map([
+  ["atproto", ATPROTO_SPEC],
+  ["sql", SQL_SPEC],
+  ["protobuf", PROTOBUF_SPEC],
+  ["graphql", GRAPHQL_SPEC],
+  ["json-schema", JSON_SCHEMA_SPEC]
+]);
+class MigrationBuilder {
+  #src;
+  #tgt;
+  #wasm;
+  #vertexMap;
+  #edgeMap;
+  #resolvers;
+  constructor(src, tgt, wasm, vertexMap = /* @__PURE__ */ new Map(), edgeMap = [], resolvers = []) {
+    this.#src = src;
+    this.#tgt = tgt;
+    this.#wasm = wasm;
+    this.#vertexMap = vertexMap;
+    this.#edgeMap = edgeMap;
+    this.#resolvers = resolvers;
+  }
+  /**
+   * Map a source vertex to a target vertex.
+   *
+   * @param srcVertex - Vertex id in the source schema
+   * @param tgtVertex - Vertex id in the target schema
+   * @returns A new builder with the mapping added
+   */
+  map(srcVertex, tgtVertex) {
+    const newMap = new Map(this.#vertexMap);
+    newMap.set(srcVertex, tgtVertex);
+    return new MigrationBuilder(
+      this.#src,
+      this.#tgt,
+      this.#wasm,
+      newMap,
+      this.#edgeMap,
+      this.#resolvers
+    );
+  }
+  /**
+   * Map a source edge to a target edge.
+   *
+   * @param srcEdge - Edge in the source schema
+   * @param tgtEdge - Edge in the target schema
+   * @returns A new builder with the edge mapping added
+   */
+  mapEdge(srcEdge, tgtEdge) {
+    return new MigrationBuilder(
+      this.#src,
+      this.#tgt,
+      this.#wasm,
+      this.#vertexMap,
+      [...this.#edgeMap, [srcEdge, tgtEdge]],
+      this.#resolvers
+    );
+  }
+  /**
+   * Add a resolver for ancestor contraction ambiguity.
+   *
+   * When a migration contracts nodes and the resulting edge between
+   * two vertex kinds is ambiguous, a resolver specifies which edge to use.
+   *
+   * @param srcKind - Source vertex kind in the contracted pair
+   * @param tgtKind - Target vertex kind in the contracted pair
+   * @param resolvedEdge - The edge to use for this pair
+   * @returns A new builder with the resolver added
+   */
+  resolve(srcKind, tgtKind, resolvedEdge) {
+    return new MigrationBuilder(
+      this.#src,
+      this.#tgt,
+      this.#wasm,
+      this.#vertexMap,
+      this.#edgeMap,
+      [...this.#resolvers, [[srcKind, tgtKind], resolvedEdge]]
+    );
+  }
+  /**
+   * Get the current migration specification.
+   *
+   * @returns The migration spec with all accumulated mappings
+   */
+  toSpec() {
+    return {
+      vertexMap: Object.fromEntries(this.#vertexMap),
+      edgeMap: [...this.#edgeMap],
+      resolvers: [...this.#resolvers]
+    };
+  }
+  /**
+   * Compile the migration for fast per-record application.
+   *
+   * Sends the migration specification to WASM for compilation.
+   * The resulting `CompiledMigration` can be used to transform records.
+   *
+   * @returns A compiled migration ready for record transformation
+   * @throws {@link MigrationError} if compilation fails
+   */
+  compile() {
+    const mapping = packMigrationMapping({
+      vertex_map: Object.fromEntries(this.#vertexMap),
+      edge_map: this.#edgeMap.map(([src, tgt]) => [
+        { src: src.src, tgt: src.tgt, kind: src.kind, name: src.name ?? null },
+        { src: tgt.src, tgt: tgt.tgt, kind: tgt.kind, name: tgt.name ?? null }
+      ]),
+      resolver: this.#resolvers.map(([[s, t], e]) => [
+        [s, t],
+        { src: e.src, tgt: e.tgt, kind: e.kind, name: e.name ?? null }
+      ])
+    });
+    try {
+      const rawHandle = this.#wasm.exports.compile_migration(
+        this.#src._handle.id,
+        this.#tgt._handle.id,
+        mapping
+      );
+      const handle = createHandle(rawHandle, this.#wasm);
+      return new CompiledMigration(handle, this.#wasm, this.toSpec());
+    } catch (error) {
+      throw new MigrationError(
+        `Failed to compile migration: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+}
+class CompiledMigration {
+  #handle;
+  #wasm;
+  #spec;
+  constructor(handle, wasm, spec) {
+    this.#handle = handle;
+    this.#wasm = wasm;
+    this.#spec = spec;
+  }
+  /** The WASM handle for this migration. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /** The migration specification used to build this migration. */
+  get spec() {
+    return this.#spec;
+  }
+  /**
+   * Transform a record using this migration (forward direction).
+   *
+   * This is the hot path: data goes through WASM as MessagePack bytes
+   * with no intermediate JS-heap allocation.
+   *
+   * @param record - The input record to transform
+   * @returns The transformed record
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  lift(record) {
+    const inputBytes = packToWasm(record);
+    try {
+      const outputBytes = this.#wasm.exports.lift_record(
+        this.#handle.id,
+        inputBytes
+      );
+      const data = unpackFromWasm(outputBytes);
+      return { data };
+    } catch (error) {
+      throw new WasmError(
+        `lift_record failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Bidirectional get: extract view and complement from a record.
+   *
+   * The complement captures data discarded by the forward projection,
+   * enabling lossless round-tripping via `put()`.
+   *
+   * @param record - The input record
+   * @returns The projected view and opaque complement bytes
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  get(record) {
+    const inputBytes = packToWasm(record);
+    try {
+      const outputBytes = this.#wasm.exports.get_record(
+        this.#handle.id,
+        inputBytes
+      );
+      const result = unpackFromWasm(outputBytes);
+      return {
+        view: result.view,
+        complement: result.complement instanceof Uint8Array ? result.complement : new Uint8Array(result.complement)
+      };
+    } catch (error) {
+      throw new WasmError(
+        `get_record failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Bidirectional put: restore a full record from a modified view and complement.
+   *
+   * @param view - The (possibly modified) projected view
+   * @param complement - The complement from a prior `get()` call
+   * @returns The restored full record
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  put(view, complement) {
+    const viewBytes = packToWasm(view);
+    try {
+      const outputBytes = this.#wasm.exports.put_record(
+        this.#handle.id,
+        viewBytes,
+        complement
+      );
+      const data = unpackFromWasm(outputBytes);
+      return { data };
+    } catch (error) {
+      throw new WasmError(
+        `put_record failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /** Release the WASM-side compiled migration resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
+}
+function checkExistence(src, tgt, spec, wasm) {
+  const mapping = packMigrationMapping({
+    vertex_map: spec.vertexMap,
+    edge_map: spec.edgeMap.map(([s, t]) => [
+      { src: s.src, tgt: s.tgt, kind: s.kind, name: s.name ?? null },
+      { src: t.src, tgt: t.tgt, kind: t.kind, name: t.name ?? null }
+    ]),
+    resolver: spec.resolvers.map(([[s, t], e]) => [
+      [s, t],
+      { src: e.src, tgt: e.tgt, kind: e.kind, name: e.name ?? null }
+    ])
+  });
+  const resultBytes = wasm.exports.check_existence(
+    src._handle.id,
+    tgt._handle.id,
+    mapping
+  );
+  return unpackFromWasm(resultBytes);
+}
+function composeMigrations(m1, m2, wasm) {
+  try {
+    const rawHandle = wasm.exports.compose_migrations(
+      m1._handle.id,
+      m2._handle.id
+    );
+    const handle = createHandle(rawHandle, wasm);
+    const composedVertexMap = {};
+    for (const [src, intermediate] of Object.entries(m1.spec.vertexMap)) {
+      const final_ = m2.spec.vertexMap[intermediate];
+      composedVertexMap[src] = final_ ?? intermediate;
+    }
+    const composedSpec = {
+      vertexMap: composedVertexMap,
+      edgeMap: [...m1.spec.edgeMap, ...m2.spec.edgeMap],
+      resolvers: [...m1.spec.resolvers, ...m2.spec.resolvers]
+    };
+    return new CompiledMigration(handle, wasm, composedSpec);
+  } catch (error) {
+    throw new MigrationError(
+      `Failed to compose migrations: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+}
+class Panproto {
+  #wasm;
+  #protocols;
+  constructor(wasm) {
+    this.#wasm = wasm;
+    this.#protocols = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Initialize the panproto SDK by loading the WASM module.
+   *
+   * @param wasmUrl - Optional URL or path to the WASM binary.
+   *                  Defaults to the bundled binary.
+   * @returns An initialized Panproto instance
+   * @throws {@link import('./types.js').WasmError} if WASM loading fails
+   */
+  static async init(wasmUrl) {
+    const wasm = await loadWasm(wasmUrl);
+    return new Panproto(wasm);
+  }
+  /**
+   * Get or register a protocol by name.
+   *
+   * If the protocol is a built-in (e.g., 'atproto', 'sql'), it is
+   * automatically registered on first access. Custom protocols must
+   * be registered first with {@link Panproto.defineProtocol}.
+   *
+   * @param name - The protocol name
+   * @returns The protocol instance
+   * @throws {@link PanprotoError} if the protocol is not found
+   */
+  protocol(name) {
+    const cached = this.#protocols.get(name);
+    if (cached) return cached;
+    const builtinSpec = BUILTIN_PROTOCOLS.get(name);
+    if (builtinSpec) {
+      const proto = defineProtocol(builtinSpec, this.#wasm);
+      this.#protocols.set(name, proto);
+      return proto;
+    }
+    throw new PanprotoError(
+      `Protocol "${name}" not found. Register it with defineProtocol() first.`
+    );
+  }
+  /**
+   * Define and register a custom protocol.
+   *
+   * @param spec - The protocol specification
+   * @returns The registered protocol
+   * @throws {@link PanprotoError} if registration fails
+   */
+  defineProtocol(spec) {
+    const proto = defineProtocol(spec, this.#wasm);
+    this.#protocols.set(spec.name, proto);
+    return proto;
+  }
+  /**
+   * Start building a migration between two schemas.
+   *
+   * @param src - The source schema
+   * @param tgt - The target schema
+   * @returns A migration builder
+   */
+  migration(src, tgt) {
+    return new MigrationBuilder(src, tgt, this.#wasm);
+  }
+  /**
+   * Check existence conditions for a proposed migration.
+   *
+   * Verifies that the migration specification satisfies all
+   * protocol-derived constraints (edge coverage, kind consistency,
+   * required fields, etc.).
+   *
+   * @param src - The source schema
+   * @param tgt - The target schema
+   * @param builder - The migration builder with mappings
+   * @returns The existence report
+   */
+  checkExistence(src, tgt, builder) {
+    return checkExistence(src, tgt, builder.toSpec(), this.#wasm);
+  }
+  /**
+   * Compose two compiled migrations into a single migration.
+   *
+   * The resulting migration is equivalent to applying `m1` then `m2`.
+   *
+   * @param m1 - First migration (applied first)
+   * @param m2 - Second migration (applied second)
+   * @returns The composed migration
+   * @throws {@link import('./types.js').MigrationError} if composition fails
+   */
+  compose(m1, m2) {
+    return composeMigrations(m1, m2, this.#wasm);
+  }
+  /**
+   * Diff two schemas and produce a compatibility report.
+   *
+   * @param oldSchema - The old/source schema
+   * @param newSchema - The new/target schema
+   * @returns A diff report with changes and compatibility classification
+   */
+  diff(oldSchema, newSchema) {
+    const resultBytes = this.#wasm.exports.diff_schemas(
+      oldSchema._handle.id,
+      newSchema._handle.id
+    );
+    return unpackFromWasm(resultBytes);
+  }
+  /**
+   * Release all WASM resources held by this instance.
+   *
+   * Disposes all cached protocols. After disposal, this instance
+   * must not be used.
+   */
+  [Symbol.dispose]() {
+    for (const proto of this.#protocols.values()) {
+      proto[Symbol.dispose]();
+    }
+    this.#protocols.clear();
+  }
+}
+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) {
+  return combinators.reduce((acc, c) => compose(acc, c));
+}
+export {
+  ATPROTO_SPEC,
+  BUILTIN_PROTOCOLS,
+  BuiltSchema,
+  CompiledMigration,
+  ExistenceCheckError,
+  GRAPHQL_SPEC,
+  JSON_SCHEMA_SPEC,
+  MigrationBuilder,
+  MigrationError,
+  PROTOBUF_SPEC,
+  Panproto,
+  PanprotoError,
+  Protocol,
+  SQL_SPEC,
+  SchemaBuilder,
+  SchemaValidationError,
+  WasmError,
+  addField,
+  coerceType,
+  compose,
+  hoistField,
+  pipeline,
+  removeField,
+  renameField,
+  wrapInObject
+};
+//# sourceMappingURL=index.js.map