@panproto/core 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { encode, decode } from "@msgpack/msgpack";
+import { decode, encode } from "@msgpack/msgpack";
 class PanprotoError extends Error {
   name = "PanprotoError";
   constructor(message, options) {
@@ -49,7 +49,48 @@ async function loadWasm(input) {
       put_record: glue.put_record,
       compose_migrations: glue.compose_migrations,
       diff_schemas: glue.diff_schemas,
-      free_handle: glue.free_handle
+      free_handle: glue.free_handle,
+      diff_schemas_full: glue.diff_schemas_full,
+      classify_diff: glue.classify_diff,
+      report_text: glue.report_text,
+      report_json: glue.report_json,
+      normalize_schema: glue.normalize_schema,
+      validate_schema: glue.validate_schema,
+      register_io_protocols: glue.register_io_protocols,
+      list_io_protocols: glue.list_io_protocols,
+      parse_instance: glue.parse_instance,
+      emit_instance: glue.emit_instance,
+      validate_instance: glue.validate_instance,
+      instance_to_json: glue.instance_to_json,
+      json_to_instance: glue.json_to_instance,
+      instance_element_count: glue.instance_element_count,
+      lens_from_combinators: glue.lens_from_combinators,
+      check_lens_laws: glue.check_lens_laws,
+      check_get_put: glue.check_get_put,
+      check_put_get: glue.check_put_get,
+      invert_migration: glue.invert_migration,
+      compose_lenses: glue.compose_lenses,
+      // Phase 4
+      list_builtin_protocols: glue.list_builtin_protocols,
+      get_builtin_protocol: glue.get_builtin_protocol,
+      // Phase 5
+      create_theory: glue.create_theory,
+      colimit_theories: glue.colimit_theories,
+      check_morphism: glue.check_morphism,
+      migrate_model: glue.migrate_model,
+      // Phase 6
+      vcs_init: glue.vcs_init,
+      vcs_add: glue.vcs_add,
+      vcs_commit: glue.vcs_commit,
+      vcs_log: glue.vcs_log,
+      vcs_status: glue.vcs_status,
+      vcs_diff: glue.vcs_diff,
+      vcs_branch: glue.vcs_branch,
+      vcs_checkout: glue.vcs_checkout,
+      vcs_merge: glue.vcs_merge,
+      vcs_stash: glue.vcs_stash,
+      vcs_stash_pop: glue.vcs_stash_pop,
+      vcs_blame: glue.vcs_blame
     };
     const memory = initOutput.memory;
     if (!memory) {
@@ -116,6 +157,280 @@ function packSchemaOps(ops) {
 function packMigrationMapping(mapping) {
   return encode(mapping);
 }
+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 LensHandle {
+  #handle;
+  #wasm;
+  constructor(handle, wasm) {
+    this.#handle = handle;
+    this.#wasm = wasm;
+  }
+  /** The underlying WASM handle. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /**
+   * Forward projection: extract the view from a record.
+   *
+   * @param record - MessagePack-encoded input record
+   * @returns The projected view and opaque complement bytes
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  get(record) {
+    try {
+      const outputBytes = this.#wasm.exports.get_record(
+        this.#handle.id,
+        record
+      );
+      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 }
+      );
+    }
+  }
+  /**
+   * Backward put: restore a full record from a modified view and complement.
+   *
+   * @param view - MessagePack-encoded (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) {
+    try {
+      const outputBytes = this.#wasm.exports.put_record(
+        this.#handle.id,
+        view,
+        complement
+      );
+      const data = unpackFromWasm(outputBytes);
+      return { data };
+    } catch (error) {
+      throw new WasmError(
+        `put_record failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Check both GetPut and PutGet lens laws for an instance.
+   *
+   * @param instance - MessagePack-encoded instance data
+   * @returns Whether both laws hold and any violation message
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  checkLaws(instance) {
+    try {
+      const resultBytes = this.#wasm.exports.check_lens_laws(
+        this.#handle.id,
+        instance
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `check_lens_laws failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Check the GetPut lens law for an instance.
+   *
+   * @param instance - MessagePack-encoded instance data
+   * @returns Whether the law holds and any violation message
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  checkGetPut(instance) {
+    try {
+      const resultBytes = this.#wasm.exports.check_get_put(
+        this.#handle.id,
+        instance
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `check_get_put failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Check the PutGet lens law for an instance.
+   *
+   * @param instance - MessagePack-encoded instance data
+   * @returns Whether the law holds and any violation message
+   * @throws {@link WasmError} if the WASM call fails
+   */
+  checkPutGet(instance) {
+    try {
+      const resultBytes = this.#wasm.exports.check_put_get(
+        this.#handle.id,
+        instance
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `check_put_get failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /** Release the underlying WASM resource. */
+  [Symbol.dispose]() {
+    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 }
+    );
+  }
+}
+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)] };
+  }
+}
+class FullDiffReport {
+  /** The raw diff data. */
+  data;
+  /** @internal */
+  _reportBytes;
+  /** @internal */
+  _wasm;
+  /** @internal */
+  constructor(data, reportBytes, wasm) {
+    this.data = data;
+    this._reportBytes = reportBytes;
+    this._wasm = wasm;
+  }
+  /** Whether there are any changes at all. */
+  get hasChanges() {
+    const d = this.data;
+    return d.added_vertices.length > 0 || d.removed_vertices.length > 0 || d.kind_changes.length > 0 || d.added_edges.length > 0 || d.removed_edges.length > 0 || Object.keys(d.modified_constraints).length > 0 || d.added_hyper_edges.length > 0 || d.removed_hyper_edges.length > 0 || d.modified_hyper_edges.length > 0 || Object.keys(d.added_required).length > 0 || Object.keys(d.removed_required).length > 0 || Object.keys(d.added_nsids).length > 0 || d.removed_nsids.length > 0 || d.changed_nsids.length > 0 || d.added_variants.length > 0 || d.removed_variants.length > 0 || d.modified_variants.length > 0 || d.order_changes.length > 0 || d.added_recursion_points.length > 0 || d.removed_recursion_points.length > 0 || d.modified_recursion_points.length > 0 || d.usage_mode_changes.length > 0 || d.added_spans.length > 0 || d.removed_spans.length > 0 || d.modified_spans.length > 0 || d.nominal_changes.length > 0;
+  }
+  /** Classify the diff against a protocol, producing a compatibility report. */
+  classify(protocol) {
+    const rawBytes = this._wasm.exports.classify_diff(
+      protocol._handle.id,
+      this._reportBytes
+    );
+    const data = unpackFromWasm(rawBytes);
+    return new CompatReport(data, rawBytes, this._wasm);
+  }
+}
+class CompatReport {
+  /** The raw report data. */
+  data;
+  /** @internal */
+  _rawBytes;
+  /** @internal */
+  _wasm;
+  /** @internal */
+  constructor(data, rawBytes, wasm) {
+    this.data = data;
+    this._rawBytes = rawBytes;
+    this._wasm = wasm;
+  }
+  /** List of breaking changes. */
+  get breakingChanges() {
+    return this.data.breaking;
+  }
+  /** List of non-breaking changes. */
+  get nonBreakingChanges() {
+    return this.data.non_breaking;
+  }
+  /** Whether the changes are fully compatible (no breaking changes). */
+  get isCompatible() {
+    return this.data.compatible;
+  }
+  /** Whether there are any breaking changes. */
+  get isBreaking() {
+    return !this.data.compatible;
+  }
+  /** Whether the changes are backward-compatible (additions only, no removals). */
+  get isBackwardCompatible() {
+    return this.data.compatible;
+  }
+  /** Render as human-readable text. */
+  toText() {
+    return this._wasm.exports.report_text(this._rawBytes);
+  }
+  /** Render as a JSON string. */
+  toJson() {
+    return this._wasm.exports.report_json(this._rawBytes);
+  }
+}
+class ValidationResult {
+  /** The list of validation issues found. */
+  issues;
+  constructor(issues) {
+    this.issues = issues;
+  }
+  /** Whether the schema is valid (no issues found). */
+  get isValid() {
+    return this.issues.length === 0;
+  }
+  /** The number of validation issues. */
+  get errorCount() {
+    return this.issues.length;
+  }
+}
 class SchemaBuilder {
   #protocolName;
   #protocolHandle;
@@ -350,7 +665,13 @@ class SchemaBuilder {
       ),
       required: Object.fromEntries(
         Array.from(this.#required.entries()).map(([k, v]) => [k, [...v]])
-      )
+      ),
+      variants: {},
+      orderings: {},
+      recursionPoints: {},
+      usageModes: {},
+      spans: {},
+      nominal: {}
     };
     return new BuiltSchema(handle, data, this.#wasm);
   }
@@ -388,6 +709,25 @@ class BuiltSchema {
   get edges() {
     return this.#data.edges;
   }
+  /** @internal Create from raw handle (used by normalize). */
+  static _fromHandle(handle, data, _protocol, wasm) {
+    const wasmHandle = createHandle(handle, wasm);
+    return new BuiltSchema(wasmHandle, data, wasm);
+  }
+  /** Normalize this schema by collapsing reference chains. Returns a new BuiltSchema. */
+  normalize() {
+    const handle = this.#wasm.exports.normalize_schema(this.#handle.id);
+    return BuiltSchema._fromHandle(handle, this.#data, this.#data.protocol, this.#wasm);
+  }
+  /** Validate this schema against a protocol's rules. */
+  validate(protocol) {
+    const bytes = this.#wasm.exports.validate_schema(
+      this.#handle.id,
+      protocol._handle.id
+    );
+    const issues = unpackFromWasm(bytes);
+    return new ValidationResult(issues);
+  }
   /** Release the WASM-side schema resource. */
   [Symbol.dispose]() {
     this.#handle[Symbol.dispose]();
@@ -410,6 +750,18 @@ class Protocol {
   get spec() {
     return this.#spec;
   }
+  /** The edge rules for this protocol. */
+  get edgeRules() {
+    return this.#spec.edgeRules;
+  }
+  /** The constraint sorts for this protocol. */
+  get constraintSorts() {
+    return this.#spec.constraintSorts;
+  }
+  /** The object kinds for this protocol. */
+  get objectKinds() {
+    return this.#spec.objKinds;
+  }
   /** The WASM handle. Internal use only. */
   get _handle() {
     return this.#handle;
@@ -550,6 +902,34 @@ const BUILTIN_PROTOCOLS = /* @__PURE__ */ new Map([
   ["graphql", GRAPHQL_SPEC],
   ["json-schema", JSON_SCHEMA_SPEC]
 ]);
+let _protocolNamesCache = null;
+function getProtocolNames(wasm) {
+  if (_protocolNamesCache !== null) return _protocolNamesCache;
+  const bytes = wasm.exports.list_builtin_protocols();
+  _protocolNamesCache = unpackFromWasm(bytes);
+  return _protocolNamesCache;
+}
+function getBuiltinProtocol(name, wasm) {
+  try {
+    const nameBytes = new TextEncoder().encode(name);
+    const bytes = wasm.exports.get_builtin_protocol(nameBytes);
+    const wire = unpackFromWasm(bytes);
+    return {
+      name: wire.name,
+      schemaTheory: wire.schema_theory,
+      instanceTheory: wire.instance_theory,
+      edgeRules: wire.edge_rules.map((r) => ({
+        edgeKind: r.edge_kind,
+        srcKinds: r.src_kinds,
+        tgtKinds: r.tgt_kinds
+      })),
+      objKinds: wire.obj_kinds,
+      constraintSorts: wire.constraint_sorts
+    };
+  } catch {
+    return void 0;
+  }
+}
 class MigrationBuilder {
   #src;
   #tgt;
@@ -634,6 +1014,50 @@ class MigrationBuilder {
       resolvers: [...this.#resolvers]
     };
   }
+  /**
+   * Invert a bijective migration.
+   *
+   * Serializes the current mapping to MessagePack and calls the
+   * `invert_migration` WASM entry point. Returns a new MigrationSpec
+   * representing the inverted migration.
+   *
+   * @returns The inverted migration specification
+   * @throws {@link MigrationError} if the migration is not bijective or inversion fails
+   */
+  invert() {
+    const edgeMap = new 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 }
+      ])
+    );
+    const resolver = new Map(
+      this.#resolvers.map(([[s, t], e]) => [
+        [s, t],
+        { src: e.src, tgt: e.tgt, kind: e.kind, name: e.name ?? null }
+      ])
+    );
+    const mapping = packMigrationMapping({
+      vertex_map: Object.fromEntries(this.#vertexMap),
+      edge_map: edgeMap,
+      hyper_edge_map: {},
+      label_map: /* @__PURE__ */ new Map(),
+      resolver
+    });
+    try {
+      const resultBytes = this.#wasm.exports.invert_migration(
+        mapping,
+        this.#src._handle.id,
+        this.#tgt._handle.id
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new MigrationError(
+        `Failed to invert migration: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
   /**
    * Compile the migration for fast per-record application.
    *
@@ -834,6 +1258,433 @@ function composeMigrations(m1, m2, wasm) {
     );
   }
 }
+class Instance {
+  /** Raw MsgPack-encoded instance bytes (for passing back to WASM). */
+  _bytes;
+  /** The schema this instance conforms to. */
+  _schema;
+  /** @internal */
+  _wasm;
+  constructor(bytes, schema, wasm) {
+    this._bytes = bytes;
+    this._schema = schema;
+    this._wasm = wasm;
+  }
+  /** Convert this instance to JSON bytes. */
+  toJson() {
+    return this._wasm.exports.instance_to_json(
+      this._schema._handle.id,
+      this._bytes
+    );
+  }
+  /** Validate this instance against its schema. */
+  validate() {
+    const resultBytes = this._wasm.exports.validate_instance(
+      this._schema._handle.id,
+      this._bytes
+    );
+    const errors = unpackFromWasm(resultBytes);
+    return {
+      isValid: errors.length === 0,
+      errors
+    };
+  }
+  /** Get the number of elements in this instance. */
+  get elementCount() {
+    return this._wasm.exports.instance_element_count(this._bytes);
+  }
+  /**
+   * Create an Instance from JSON input.
+   *
+   * @param schema - The schema the JSON data conforms to
+   * @param json - JSON bytes
+   * @param wasm - The WASM module
+   * @returns A new Instance
+   */
+  static fromJson(schema, json, wasm) {
+    const bytes = wasm.exports.json_to_instance(schema._handle.id, json);
+    return new Instance(bytes, schema, wasm);
+  }
+}
+const PROTOCOL_CATEGORIES = {
+  annotation: [
+    "brat",
+    "conllu",
+    "naf",
+    "uima",
+    "folia",
+    "tei",
+    "timeml",
+    "elan",
+    "iso_space",
+    "paula",
+    "laf_graf",
+    "decomp",
+    "ucca",
+    "fovea",
+    "bead",
+    "web_annotation",
+    "amr",
+    "concrete",
+    "nif"
+  ],
+  api: ["graphql", "openapi", "asyncapi", "jsonapi", "raml"],
+  config: ["cloudformation", "ansible", "k8s_crd", "hcl"],
+  data_schema: [
+    "json_schema",
+    "yaml_schema",
+    "toml_schema",
+    "cddl",
+    "bson",
+    "csv_table",
+    "ini_schema"
+  ],
+  data_science: ["dataframe", "parquet", "arrow"],
+  database: ["mongodb", "dynamodb", "cassandra", "neo4j", "sql", "redis"],
+  domain: ["geojson", "fhir", "rss_atom", "vcard_ical", "swift_mt", "edi_x12"],
+  serialization: [
+    "protobuf",
+    "avro",
+    "thrift",
+    "capnproto",
+    "flatbuffers",
+    "asn1",
+    "bond",
+    "msgpack_schema"
+  ],
+  type_system: [
+    "typescript",
+    "python",
+    "rust_serde",
+    "java",
+    "go_struct",
+    "kotlin",
+    "csharp",
+    "swift"
+  ],
+  web_document: [
+    "atproto",
+    "jsx",
+    "vue",
+    "svelte",
+    "css",
+    "html",
+    "markdown",
+    "xml_xsd",
+    "docx",
+    "odf"
+  ]
+};
+const encoder$1 = new TextEncoder();
+class IoRegistry {
+  _handle;
+  _wasm;
+  _protocolsCache = null;
+  constructor(handle, wasm) {
+    this._handle = handle;
+    this._wasm = wasm;
+  }
+  /**
+   * List all registered protocol names.
+   *
+   * The result is cached after the first call.
+   */
+  get protocols() {
+    if (this._protocolsCache === null) {
+      const bytes = this._wasm.exports.list_io_protocols(this._handle.id);
+      this._protocolsCache = unpackFromWasm(bytes);
+    }
+    return this._protocolsCache;
+  }
+  /** Protocol names organized by category. */
+  get categories() {
+    return PROTOCOL_CATEGORIES;
+  }
+  /** Check if a protocol is registered. */
+  hasProtocol(name) {
+    return this.protocols.includes(name);
+  }
+  /**
+   * Parse raw format bytes into an Instance.
+   *
+   * @param protocolName - The protocol codec name (e.g., 'graphql', 'protobuf')
+   * @param schema - The schema the data conforms to
+   * @param input - Raw format bytes to parse
+   * @returns A new Instance wrapping the parsed data
+   * @throws {@link PanprotoError} if the protocol is not registered or parsing fails
+   */
+  parse(protocolName, schema, input) {
+    const nameBytes = encoder$1.encode(protocolName);
+    const resultBytes = this._wasm.exports.parse_instance(
+      this._handle.id,
+      nameBytes,
+      schema._handle.id,
+      input
+    );
+    return new Instance(resultBytes, schema, this._wasm);
+  }
+  /**
+   * Emit an Instance to raw format bytes.
+   *
+   * @param protocolName - The protocol codec name (e.g., 'graphql', 'protobuf')
+   * @param schema - The schema the instance conforms to
+   * @param instance - The instance to emit
+   * @returns Raw format bytes
+   * @throws {@link PanprotoError} if the protocol is not registered or emission fails
+   */
+  emit(protocolName, schema, instance) {
+    const nameBytes = encoder$1.encode(protocolName);
+    return this._wasm.exports.emit_instance(
+      this._handle.id,
+      nameBytes,
+      schema._handle.id,
+      instance._bytes
+    );
+  }
+  /** Release the WASM-side IoRegistry resource. */
+  [Symbol.dispose]() {
+    this._handle[Symbol.dispose]();
+  }
+}
+const encoder = new TextEncoder();
+class Repository {
+  #handle;
+  #wasm;
+  #protocolName;
+  constructor(handle, protocolName, wasm) {
+    this.#handle = handle;
+    this.#protocolName = protocolName;
+    this.#wasm = wasm;
+  }
+  /**
+   * Initialize a new in-memory repository.
+   *
+   * @param protocolName - The protocol this repository tracks
+   * @param wasm - The WASM module
+   * @returns A new disposable Repository
+   */
+  static init(protocolName, wasm) {
+    const nameBytes = encoder.encode(protocolName);
+    const rawHandle = wasm.exports.vcs_init(nameBytes);
+    const handle = createHandle(rawHandle, wasm);
+    return new Repository(handle, protocolName, wasm);
+  }
+  /** The protocol name this repository tracks. */
+  get protocolName() {
+    return this.#protocolName;
+  }
+  /** The underlying WASM handle. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /**
+   * Stage a schema for the next commit.
+   *
+   * @param schema - The built schema to stage
+   * @returns An object with the schema's object ID
+   */
+  add(schema) {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_add(
+        this.#handle.id,
+        schema._handle.id
+      );
+      const result = unpackFromWasm(resultBytes);
+      return { schemaId: result.schema_id };
+    } catch (error) {
+      throw new WasmError(
+        `vcs_add failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Create a commit from the current staging area.
+   *
+   * @param message - The commit message
+   * @param author - The commit author
+   * @returns The commit result
+   */
+  commit(message, author) {
+    try {
+      return this.#wasm.exports.vcs_commit(
+        this.#handle.id,
+        encoder.encode(message),
+        encoder.encode(author)
+      );
+    } catch (error) {
+      throw new WasmError(
+        `vcs_commit failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Walk the commit log from HEAD.
+   *
+   * @param count - Maximum number of log entries to return (default: 50)
+   * @returns Array of commit log entries
+   */
+  log(count = 50) {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_log(this.#handle.id, count);
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_log failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get the repository status.
+   *
+   * @returns Current branch and HEAD commit info
+   */
+  status() {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_status(this.#handle.id);
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_status failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get diff information for the repository.
+   *
+   * @returns Diff result with branch info
+   */
+  diff() {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_diff(this.#handle.id);
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_diff failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Create a new branch at the current HEAD.
+   *
+   * @param name - The branch name
+   * @returns Operation result
+   */
+  branch(name) {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_branch(
+        this.#handle.id,
+        encoder.encode(name)
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_branch failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Checkout a branch.
+   *
+   * @param target - The branch name to checkout
+   * @returns Operation result
+   */
+  checkout(target) {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_checkout(
+        this.#handle.id,
+        encoder.encode(target)
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_checkout failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Merge a branch into the current branch.
+   *
+   * @param branchName - The branch to merge
+   * @returns Operation result
+   */
+  merge(branchName) {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_merge(
+        this.#handle.id,
+        encoder.encode(branchName)
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_merge failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Stash the current working state.
+   *
+   * @returns Operation result
+   */
+  stash() {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_stash(this.#handle.id);
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_stash failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Pop the most recent stash entry.
+   *
+   * @returns Operation result
+   */
+  stashPop() {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_stash_pop(this.#handle.id);
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_stash_pop failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Find which commit introduced a vertex.
+   *
+   * @param vertexId - The vertex ID to blame
+   * @returns Blame result with commit info
+   */
+  blame(vertexId) {
+    try {
+      const resultBytes = this.#wasm.exports.vcs_blame(
+        this.#handle.id,
+        encoder.encode(vertexId)
+      );
+      return unpackFromWasm(resultBytes);
+    } catch (error) {
+      throw new WasmError(
+        `vcs_blame failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /** Release the WASM-side repository resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
+}
 class Panproto {
   #wasm;
   #protocols;
@@ -874,6 +1725,12 @@ class Panproto {
       this.#protocols.set(name, proto);
       return proto;
     }
+    const wasmSpec = getBuiltinProtocol(name, this.#wasm);
+    if (wasmSpec) {
+      const proto = defineProtocol(wasmSpec, this.#wasm);
+      this.#protocols.set(name, proto);
+      return proto;
+    }
     throw new PanprotoError(
       `Protocol "${name}" not found. Register it with defineProtocol() first.`
     );
@@ -934,6 +1791,31 @@ class Panproto {
   compose(m1, m2) {
     return composeMigrations(m1, m2, this.#wasm);
   }
+  /**
+   * Compose two lenses into a single lens.
+   *
+   * The resulting lens is equivalent to applying `l1` then `l2`.
+   *
+   * @param l1 - First lens (applied first)
+   * @param l2 - Second lens (applied second)
+   * @returns A new LensHandle representing the composition
+   * @throws {@link import('./types.js').WasmError} if composition fails
+   */
+  composeLenses(l1, l2) {
+    try {
+      const rawHandle = this.#wasm.exports.compose_lenses(
+        l1._handle.id,
+        l2._handle.id
+      );
+      const handle = createHandle(rawHandle, this.#wasm);
+      return new LensHandle(handle, this.#wasm);
+    } catch (error) {
+      throw new WasmError(
+        `compose_lenses failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
   /**
    * Diff two schemas and produce a compatibility report.
    *
@@ -948,6 +1830,90 @@ class Panproto {
     );
     return unpackFromWasm(resultBytes);
   }
+  /** Diff two schemas using the full panproto-check engine (20+ change categories). */
+  diffFull(oldSchema, newSchema) {
+    const bytes = this.#wasm.exports.diff_schemas_full(
+      oldSchema._handle.id,
+      newSchema._handle.id
+    );
+    const data = unpackFromWasm(bytes);
+    return new FullDiffReport(data, bytes, this.#wasm);
+  }
+  /** Normalize a schema by collapsing reference chains. Returns a new BuiltSchema. */
+  normalize(schema) {
+    const handle = this.#wasm.exports.normalize_schema(schema._handle.id);
+    return BuiltSchema._fromHandle(handle, schema.data, schema.protocol, this.#wasm);
+  }
+  /** Validate a schema against its protocol's rules. */
+  validateSchema(schema, protocol) {
+    const bytes = this.#wasm.exports.validate_schema(
+      schema._handle.id,
+      protocol._handle.id
+    );
+    const issues = unpackFromWasm(bytes);
+    return new ValidationResult(issues);
+  }
+  /**
+   * Create an I/O protocol registry for parsing and emitting instances.
+   *
+   * The returned registry wraps all 77 built-in protocol codecs and
+   * implements `Disposable` for automatic cleanup.
+   *
+   * @returns A new IoRegistry
+   */
+  io() {
+    const rawHandle = this.#wasm.exports.register_io_protocols();
+    const handle = createHandle(rawHandle, this.#wasm);
+    return new IoRegistry(handle, this.#wasm);
+  }
+  /**
+   * Parse JSON bytes into an Instance.
+   *
+   * Convenience method that wraps `json_to_instance`.
+   *
+   * @param schema - The schema the JSON data conforms to
+   * @param json - JSON bytes or a JSON string
+   * @returns A new Instance
+   */
+  parseJson(schema, json) {
+    const jsonBytes = typeof json === "string" ? new TextEncoder().encode(json) : json;
+    return Instance.fromJson(schema, jsonBytes, this.#wasm);
+  }
+  /**
+   * Convert an Instance to JSON bytes.
+   *
+   * Convenience method that wraps `instance_to_json`.
+   *
+   * @param schema - The schema the instance conforms to
+   * @param instance - The instance to convert
+   * @returns JSON bytes
+   */
+  toJson(schema, instance) {
+    return this.#wasm.exports.instance_to_json(
+      schema._handle.id,
+      instance._bytes
+    );
+  }
+  /**
+   * List all built-in protocol names.
+   *
+   * Returns the names of all 76 built-in protocols supported by the
+   * WASM layer.
+   *
+   * @returns Array of protocol name strings
+   */
+  listProtocols() {
+    return [...getProtocolNames(this.#wasm)];
+  }
+  /**
+   * Initialize an in-memory VCS repository.
+   *
+   * @param protocolName - The protocol name for this repository
+   * @returns A disposable VCS Repository
+   */
+  initRepo(protocolName) {
+    return Repository.init(protocolName, this.#wasm);
+  }
   /**
    * Release all WASM resources held by this instance.
    *
@@ -961,53 +1927,165 @@ class Panproto {
     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 };
+class TheoryHandle {
+  #handle;
+  /** @internal Retained for future sort/op inspection methods. */
+  _wasm;
+  constructor(handle, wasm) {
+    this.#handle = handle;
+    this._wasm = wasm;
+  }
+  /** The WASM handle. Internal use only. */
+  get _handle() {
+    return this.#handle;
+  }
+  /** Release the WASM-side theory resource. */
+  [Symbol.dispose]() {
+    this.#handle[Symbol.dispose]();
+  }
 }
-function wrapInObject(fieldName) {
-  return { type: "wrap-in-object", fieldName };
+class TheoryBuilder {
+  #name;
+  #extends;
+  #sorts;
+  #ops;
+  #eqs;
+  constructor(name) {
+    this.#name = name;
+    this.#extends = [];
+    this.#sorts = [];
+    this.#ops = [];
+    this.#eqs = [];
+  }
+  /** Declare that this theory extends a parent theory. */
+  extends(parentName) {
+    this.#extends.push(parentName);
+    return this;
+  }
+  /** Add a simple sort (no parameters). */
+  sort(name) {
+    this.#sorts.push({ name, params: [] });
+    return this;
+  }
+  /** Add a dependent sort with parameters. */
+  dependentSort(name, params) {
+    this.#sorts.push({ name, params });
+    return this;
+  }
+  /** Add an operation. */
+  op(name, inputs, output) {
+    this.#ops.push({ name, inputs, output });
+    return this;
+  }
+  /** Add an equation (axiom). */
+  eq(name, lhs, rhs) {
+    this.#eqs.push({ name, lhs, rhs });
+    return this;
+  }
+  /** Get the theory specification. */
+  toSpec() {
+    return {
+      name: this.#name,
+      extends: this.#extends,
+      sorts: this.#sorts,
+      ops: this.#ops,
+      eqs: this.#eqs
+    };
+  }
+  /**
+   * Build the theory and register it in WASM.
+   *
+   * @param wasm - The WASM module
+   * @returns A disposable TheoryHandle
+   * @throws {@link PanprotoError} if the WASM call fails
+   */
+  build(wasm) {
+    return createTheory(this.toSpec(), wasm);
+  }
 }
-function hoistField(host, field) {
-  return { type: "hoist-field", host, field };
+function createTheory(spec, wasm) {
+  try {
+    const bytes = packToWasm(spec);
+    const rawHandle = wasm.exports.create_theory(bytes);
+    const handle = createHandle(rawHandle, wasm);
+    return new TheoryHandle(handle, wasm);
+  } catch (error) {
+    throw new PanprotoError(
+      `Failed to create theory "${spec.name}": ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
 }
-function coerceType(fromKind, toKind) {
-  return { type: "coerce-type", fromKind, toKind };
+function colimit(t1, t2, shared, wasm) {
+  try {
+    const rawHandle = wasm.exports.colimit_theories(
+      t1._handle.id,
+      t2._handle.id,
+      shared._handle.id
+    );
+    const handle = createHandle(rawHandle, wasm);
+    return new TheoryHandle(handle, wasm);
+  } catch (error) {
+    throw new WasmError(
+      `colimit_theories failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
 }
-function compose(first, second) {
-  return { type: "compose", first, second };
+function checkMorphism(morphism, domain, codomain, wasm) {
+  const morphBytes = packToWasm(morphism);
+  const resultBytes = wasm.exports.check_morphism(
+    morphBytes,
+    domain._handle.id,
+    codomain._handle.id
+  );
+  return unpackFromWasm(resultBytes);
 }
-function pipeline(combinators) {
-  const [first, ...rest] = combinators;
-  return rest.reduce((acc, c) => compose(acc, c), first);
+function migrateModel(sortInterp, morphism, wasm) {
+  const modelBytes = packToWasm(sortInterp);
+  const morphBytes = packToWasm(morphism);
+  const resultBytes = wasm.exports.migrate_model(modelBytes, morphBytes);
+  return unpackFromWasm(resultBytes);
 }
 export {
   ATPROTO_SPEC,
   BUILTIN_PROTOCOLS,
   BuiltSchema,
+  CompatReport,
   CompiledMigration,
   ExistenceCheckError,
+  FullDiffReport,
   GRAPHQL_SPEC,
+  Instance,
+  IoRegistry,
   JSON_SCHEMA_SPEC,
+  LensHandle,
   MigrationBuilder,
   MigrationError,
   PROTOBUF_SPEC,
+  PROTOCOL_CATEGORIES,
   Panproto,
   PanprotoError,
   Protocol,
+  Repository,
   SQL_SPEC,
   SchemaBuilder,
   SchemaValidationError,
+  TheoryBuilder,
+  TheoryHandle,
+  ValidationResult,
   WasmError,
   addField,
+  checkMorphism,
   coerceType,
+  colimit,
   compose,
+  createTheory,
+  fromCombinators,
+  getBuiltinProtocol,
+  getProtocolNames,
   hoistField,
+  migrateModel,
   pipeline,
   removeField,
   renameField,