@panproto/core 0.6.0 → 0.8.0

package/README.md

@@ -3,9 +3,9 @@
 [![npm](https://img.shields.io/npm/v/@panproto/core)](https://www.npmjs.com/package/@panproto/core)
 [![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
 
-TypeScript SDK for panproto. Protocol-aware schema migration via [generalized algebraic theories](https://ncatlab.org/nlab/show/generalized+algebraic+theory).
+TypeScript SDK for panproto. Protocol-aware schema migration via [generalized algebraic theories](https://ncatlab.org/nlab/show/generalized+algebraic+theory), with automatic lens generation via [protolenses](https://ncatlab.org/nlab/show/natural+transformation).
 
-This package wraps the panproto WASM module, providing a typed, ergonomic API for defining protocols, building schemas, computing migrations, and applying lens-based transformations from JavaScript and TypeScript.
+This package wraps the panproto WASM module, providing a typed, ergonomic API for defining protocols, building schemas, computing migrations, and applying protolens-based transformations from JavaScript and TypeScript.
 
 Requires Node.js >= 20.
 
@@ -23,26 +23,35 @@ import { Panproto } from '@panproto/core';
 const panproto = await Panproto.init();
 const atproto = panproto.protocol('atproto');
 
-// Build a schema
-const schema = atproto.schema()
+// Build schemas
+const oldSchema = atproto.schema()
   .vertex('post', 'record', { nsid: 'app.bsky.feed.post' })
   .vertex('post:body', 'object')
   .edge('post', 'post:body', 'record-schema')
   .build();
 
-// Diff two schemas
-const diff = panproto.diff(oldSchema, newSchema);
+const newSchema = atproto.schema()
+  .vertex('post', 'record', { nsid: 'app.bsky.feed.post' })
+  .vertex('post:body', 'object')
+  .vertex('post:body.title', 'string')
+  .edge('post', 'post:body', 'record-schema')
+  .edge('post:body', 'post:body.title', 'prop', { name: 'title' })
+  .build();
+
+// One-liner data conversion between schema versions
+const converted = panproto.convert(record, oldSchema, newSchema);
 
-// Compile and apply a migration
-const migration = panproto.migration(srcSchema, tgtSchema)
-  .map('old_id', 'new_id')
-  .compile();
+// Auto-generate a lens with full control
+const lens = panproto.lens(oldSchema, newSchema);
+const { view, complement } = lens.get(record);
+const restored = lens.put(modifiedView, complement);
 
-const lifted = migration.lift(record);
+// Build a reusable protolens chain (schema-independent)
+const chain = panproto.protolensChain(oldSchema, newSchema);
+const result = chain.apply(record);
 
-// Bidirectional lens
-const { view, complement } = migration.get(record);
-const restored = migration.put(modifiedView, complement);
+// Factorize a theory morphism into elementary steps
+const factors = panproto.factorizeMorphism(morphism);
 ```
 
 ## API
@@ -52,6 +61,10 @@ const restored = migration.put(modifiedView, complement);
 | Export | Description |
 |--------|-------------|
 | `Panproto` | Main entry point; call `Panproto.init()` to load the WASM module |
+| `Panproto.convert()` | One-liner data conversion between two schemas via auto-generated protolens |
+| `Panproto.lens()` | Auto-generate a lens between two schemas |
+| `Panproto.protolensChain()` | Build a reusable, schema-independent protolens chain |
+| `Panproto.factorizeMorphism()` | Decompose a theory morphism into elementary endofunctors |
 | `Protocol` | Protocol handle with schema builder factory |
 | `SchemaBuilder` / `BuiltSchema` | Fluent schema construction |
 | `MigrationBuilder` / `CompiledMigration` | Migration construction, compilation, and application |
@@ -59,13 +72,22 @@ const restored = migration.put(modifiedView, complement);
 | `IoRegistry` | Protocol-aware parse/emit for all 76 formats |
 | `Repository` | Schematic version control (init, commit, branch, merge) |
 
-### Lens combinators
+### Protolenses
 
 | Export | Description |
 |--------|-------------|
-| `renameField` / `addField` / `removeField` | Field-level transformations |
-| `wrapInObject` / `hoistField` / `coerceType` | Structural transformations |
-| `compose` / `pipeline` | Cambria-style combinator composition |
+| `LensHandle` | Lens with `get`, `put`, and `autoGenerate()` for automatic lens derivation |
+| `LensHandle.autoGenerate()` | Auto-generate a lens between two schemas |
+| `ProtolensChainHandle` | Reusable, schema-independent protolens chain with `apply` and `instantiate` |
+| `ProtolensChainHandle.fuse()` | Fuse chain into single step |
+| `ProtolensChainHandle.checkApplicability()` | Check applicability with reasons |
+| `ProtolensChainHandle.applyToFleet()` | Apply to multiple schemas |
+| `ProtolensChainHandle.lift()` | Lift along theory morphism |
+| `ProtolensChainHandle.fromJson()` | Deserialize from JSON |
+| `SymmetricLensHandle` | Symmetric (bidirectional) lens for two-way synchronization |
+| `DataSetHandle` | Handle to versioned data set with migrate/staleness methods |
+| `Panproto.dataSet()` | Store and track a data set |
+| `Panproto.migrateData()` | Migrate data between schemas |
 
 ### Breaking change analysis
 

package/dist/coverage.d.ts

@@ -0,0 +1,58 @@
+import { CoverageReport, OpticKind } from './types.js';
+import { BuiltSchema } from './schema.js';
+import { CompiledMigration } from './migration.js';
+import { ProtolensChainHandle } from './lens.js';
+import { Panproto } from './panproto.js';
+/**
+ * Migration analysis utilities for dry-run testing and optic classification.
+ *
+ * Wraps a `Panproto` instance and provides coverage analysis for migrations
+ * and optic kind classification for protolens chains.
+ *
+ * @example
+ * ```typescript
+ * const panproto = await Panproto.init();
+ * const analysis = new MigrationAnalysis(panproto);
+ *
+ * const report = analysis.dryRun(compiled, records, srcSchema, tgtSchema);
+ * console.log(`Coverage: ${(report.coverageRatio * 100).toFixed(1)}%`);
+ *
+ * const chain = panproto.protolensChain(srcSchema, tgtSchema);
+ * const kind = analysis.opticKind(chain, srcSchema);
+ * ```
+ */
+export declare class MigrationAnalysis {
+    #private;
+    /**
+     * Create a new migration analysis instance.
+     *
+     * @param panproto - The Panproto instance providing WASM access
+     */
+    constructor(panproto: Panproto);
+    /**
+     * 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: CompiledMigration, instances: unknown[], srcSchema: BuiltSchema, tgtSchema: BuiltSchema): CoverageReport;
+    /**
+     * 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: ProtolensChainHandle, schema: BuiltSchema): OpticKind;
+}
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEV,cAAc,EAGd,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAuJ9C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;;IAG5B;;;;OAIG;gBACS,QAAQ,EAAE,QAAQ;IAI9B;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,OAAO,EAAE,EACpB,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,WAAW,GACrB,cAAc;IAIjB;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS;CAGvE"}

package/dist/data.d.ts

@@ -0,0 +1,38 @@
+import { WasmModule } from './types.js';
+import { WasmHandle } from './wasm.js';
+import { BuiltSchema } from './schema.js';
+/** A handle to a versioned data set in the WASM store. */
+export declare class DataSetHandle implements Disposable {
+    #private;
+    constructor(handle: WasmHandle, wasm: WasmModule);
+    /** The WASM handle for this data set. Internal use only. */
+    get _handle(): WasmHandle;
+    /** Store a data set from a JavaScript object, bound to a schema. */
+    static fromData(data: unknown, schema: BuiltSchema, wasm: WasmModule): DataSetHandle;
+    /** Retrieve the data as MessagePack-encoded bytes. */
+    getData(): unknown;
+    /** Migrate this data set forward to a new schema. */
+    migrateForward(srcSchema: BuiltSchema, tgtSchema: BuiltSchema): MigrationResult;
+    /** Migrate this data set backward using a complement. */
+    migrateBackward(complement: Uint8Array, srcSchema: BuiltSchema, tgtSchema: BuiltSchema): DataSetHandle;
+    /** Check if this data set is stale relative to a schema. */
+    isStale(schema: BuiltSchema): StalenessResult;
+    [Symbol.dispose](): void;
+}
+/** Result of a forward data migration. */
+export interface MigrationResult {
+    /** The migrated data set at the target schema. */
+    readonly data: DataSetHandle;
+    /** The complement bytes needed for backward migration. */
+    readonly complement: Uint8Array;
+}
+/** Result of a staleness check. */
+export interface StalenessResult {
+    /** Whether the data set is stale relative to the target schema. */
+    readonly stale: boolean;
+    /** The schema ID the data was written against. */
+    readonly dataSchemaId: string;
+    /** The schema ID being compared to. */
+    readonly targetSchemaId: string;
+}
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,0DAA0D;AAC1D,qBAAa,aAAc,YAAW,UAAU;;gBAIlC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAKhD,4DAA4D;IAC5D,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,oEAAoE;IACpE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,aAAa;IAMpF,sDAAsD;IACtD,OAAO,IAAI,OAAO;IAKlB,qDAAqD;IACrD,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,GAAG,eAAe;IAmB/E,yDAAyD;IACzD,eAAe,CACb,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,WAAW,GACrB,aAAa;IAUhB,4DAA4D;IAC5D,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe;IAiB7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC"}

package/dist/enrichment.d.ts

@@ -0,0 +1,146 @@
+import { Expr, ConflictStrategy, EnrichmentSummary } from './types.js';
+import { BuiltSchema } from './schema.js';
+/**
+ * An individual default enrichment entry.
+ *
+ * Binds a default expression to a vertex, used when forward migration
+ * encounters a missing value.
+ */
+interface DefaultEntry {
+    readonly vertex: string;
+    readonly expr: Expr;
+}
+/**
+ * An individual coercion enrichment entry.
+ *
+ * Defines how to convert values from one kind to another.
+ */
+interface CoercionEntry {
+    readonly from: string;
+    readonly to: string;
+    readonly expr: Expr;
+}
+/**
+ * An individual merger enrichment entry.
+ *
+ * Defines how to merge two values at a given vertex during conflict resolution.
+ */
+interface MergerEntry {
+    readonly vertex: string;
+    readonly expr: Expr;
+}
+/**
+ * An individual conflict policy enrichment entry.
+ *
+ * Determines the strategy for resolving conflicts at a vertex.
+ */
+interface PolicyEntry {
+    readonly vertex: string;
+    readonly strategy: ConflictStrategy;
+}
+/**
+ * Immutable fluent builder for enriching a schema with default expressions,
+ * coercion functions, merge strategies, and conflict policies.
+ *
+ * Each mutation method returns a new `SchemaEnrichment` instance,
+ * leaving the original unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { SchemaEnrichment } from '@panproto/core';
+ * import { ExprBuilder } from '@panproto/core';
+ *
+ * const enriched = new SchemaEnrichment(schema)
+ *   .addDefault('post:title', ExprBuilder.lit({ type: 'str', value: 'Untitled' }))
+ *   .addCoercion('int', 'float', ExprBuilder.builtin('IntToFloat', ExprBuilder.var_('x')))
+ *   .addPolicy('post:body', { type: 'keep_left' })
+ *   .build();
+ * ```
+ */
+export declare class SchemaEnrichment {
+    #private;
+    constructor(schema: BuiltSchema, defaults?: readonly DefaultEntry[], coercions?: readonly CoercionEntry[], mergers?: readonly MergerEntry[], policies?: readonly PolicyEntry[]);
+    /**
+     * 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: string, expr: Expr): SchemaEnrichment;
+    /**
+     * 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: string, toKind: string, expr: Expr): SchemaEnrichment;
+    /**
+     * 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: string, expr: Expr): SchemaEnrichment;
+    /**
+     * 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: string, strategy: ConflictStrategy): SchemaEnrichment;
+    /**
+     * 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: string): SchemaEnrichment;
+    /**
+     * 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: string, toKind: string): SchemaEnrichment;
+    /**
+     * List all enrichments currently attached.
+     *
+     * @returns An enrichment summary with defaults, coercions, mergers, and policies
+     */
+    listEnrichments(): EnrichmentSummary;
+    /**
+     * 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(): BuiltSchema;
+}
+export {};
+//# sourceMappingURL=enrichment.d.ts.map

package/dist/enrichment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment.d.ts","sourceRoot":"","sources":["../src/enrichment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,UAAU,YAAY;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;;gBAQzB,MAAM,EAAE,WAAW,EACnB,QAAQ,GAAE,SAAS,YAAY,EAAO,EACtC,SAAS,GAAE,SAAS,aAAa,EAAO,EACxC,OAAO,GAAE,SAAS,WAAW,EAAO,EACpC,QAAQ,GAAE,SAAS,WAAW,EAAO;IASvC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB;IAkBxD;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB;IAgB3E;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB;IAkBvD;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB;IAkBvE;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAiB/C;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAmBlE;;;;OAIG;IACH,eAAe,IAAI,iBAAiB;IASpC;;;;;;;;OAQG;IACH,KAAK,IAAI,WAAW;CAyErB"}

package/dist/expr.d.ts

@@ -0,0 +1,145 @@
+import { Expr, Literal, Pattern, BuiltinOp } from './types.js';
+/**
+ * Static factory for constructing expression AST nodes.
+ *
+ * All methods return immutable {@link Expr} values suitable for use in
+ * schema enrichments, directed equations, and conflict policies.
+ *
+ * @example
+ * ```typescript
+ * import { ExprBuilder as E } from '@panproto/core';
+ *
+ * // Lambda that adds 1 to its argument
+ * const addOne = E.lam('x', E.add(E.var_('x'), E.lit({ type: 'int', value: 1 })));
+ *
+ * // Record literal
+ * const record = E.record({ name: E.lit({ type: 'str', value: 'default' }) });
+ * ```
+ */
+export declare class ExprBuilder {
+    /** This class is not instantiable; all methods are static. */
+    private constructor();
+    /**
+     * Create a variable reference expression.
+     *
+     * @param name - The variable name to reference
+     * @returns A variable expression node
+     */
+    static var_(name: string): Expr;
+    /**
+     * Create a literal expression.
+     *
+     * @param value - The literal value
+     * @returns A literal expression node
+     */
+    static lit(value: Literal): Expr;
+    /**
+     * 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: string, body: Expr): Expr;
+    /**
+     * 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: Expr, ...args: Expr[]): Expr;
+    /**
+     * 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: string, value: Expr, body: Expr): Expr;
+    /**
+     * 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: Expr, name: string): Expr;
+    /**
+     * Create a record literal expression.
+     *
+     * @param fields - A mapping of field names to expressions
+     * @returns A record expression node
+     */
+    static record(fields: Record<string, Expr>): Expr;
+    /**
+     * Create a list literal expression.
+     *
+     * @param items - The list element expressions
+     * @returns A list expression node
+     */
+    static list(...items: Expr[]): Expr;
+    /**
+     * 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: Expr, arms: [Pattern, Expr][]): Expr;
+    /**
+     * 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: BuiltinOp, ...args: Expr[]): Expr;
+    /**
+     * 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: Expr, index: Expr): Expr;
+    /**
+     * Add two expressions.
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Add' expression
+     */
+    static add(a: Expr, b: Expr): Expr;
+    /**
+     * Subtract two expressions.
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Sub' expression
+     */
+    static sub(a: Expr, b: Expr): Expr;
+    /**
+     * Multiply two expressions.
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Mul' expression
+     */
+    static mul(a: Expr, b: Expr): Expr;
+    /**
+     * Concatenate two expressions (strings or lists).
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Concat' expression
+     */
+    static concat(a: Expr, b: Expr): Expr;
+}
+//# sourceMappingURL=expr.d.ts.map

package/dist/expr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr.d.ts","sourceRoot":"","sources":["../src/expr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,8DAA8D;IAC9D,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAIhC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAI3C;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI;IAQ7C;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAIxD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI;IAKjD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAInC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI;IAI7D;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI;IAIpD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,IAAI;IAQ3C;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;CAGtC"}

package/dist/gat.d.ts

@@ -1,5 +1,6 @@
 import { WasmModule, TheorySpec, TheoryMorphism, MorphismCheckResult } from './types.js';
 import { WasmHandle } from './wasm.js';
+import { ElementaryStep } from './protolens.js';
 /**
  * A disposable handle to a WASM-side Theory resource.
  *
@@ -96,4 +97,19 @@ export declare function checkMorphism(morphism: TheoryMorphism, domain: TheoryHa
  * @returns Reindexed sort interpretations
  */
 export declare function migrateModel(sortInterp: Record<string, unknown[]>, morphism: TheoryMorphism, wasm: WasmModule): Record<string, unknown[]>;
+/**
+ * Factorize a morphism into elementary steps.
+ *
+ * Decomposes a theory morphism into a sequence of elementary schema
+ * transformations (renames, additions, removals, etc.) suitable for
+ * constructing protolens chains.
+ *
+ * @param morphismBytes - MessagePack-encoded morphism data
+ * @param domain - Handle to the domain theory
+ * @param codomain - Handle to the codomain theory
+ * @param wasm - The WASM module
+ * @returns A sequence of elementary steps
+ * @throws {@link WasmError} if factorization fails
+ */
+export declare function factorizeMorphism(morphismBytes: Uint8Array, domain: TheoryHandle, codomain: TheoryHandle, wasm: WasmModule): ElementaryStep[];
 //# sourceMappingURL=gat.d.ts.map

package/dist/gat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gat.d.ts","sourceRoot":"","sources":["../src/gat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,mBAAmB,EAIpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAGrD;;;;GAIG;AACH,qBAAa,YAAa,YAAW,UAAU;;IAE7C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAKhD,0CAA0C;IAC1C,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,6CAA6C;IAC7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;;gBAOZ,IAAI,EAAE,MAAM;IAQxB,wDAAwD;IACxD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKjC,yCAAyC;IACzC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,4CAA4C;IAC5C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAK3E,wBAAwB;IACxB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlE,+BAA+B;IAC/B,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,GAAG,IAAI;IAKtF,oCAAoC;IACpC,MAAM,IAAI,UAAU;IAUpB;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY;CAGtC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,YAAY,CAY7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,YAAY,CAed;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,UAAU,GACf,mBAAmB,CAQrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACrC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAK3B"}
+{"version":3,"file":"gat.d.ts","sourceRoot":"","sources":["../src/gat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,mBAAmB,EAIpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;GAIG;AACH,qBAAa,YAAa,YAAW,UAAU;;IAE7C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAKhD,0CAA0C;IAC1C,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,6CAA6C;IAC7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;;gBAOZ,IAAI,EAAE,MAAM;IAQxB,wDAAwD;IACxD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKjC,yCAAyC;IACzC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,4CAA4C;IAC5C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAK3E,wBAAwB;IACxB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlE,+BAA+B;IAC/B,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,GAAG,IAAI;IAKtF,oCAAoC;IACpC,MAAM,IAAI,UAAU;IAUpB;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY;CAGtC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,YAAY,CAY7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,YAAY,CAed;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,UAAU,GACf,mBAAmB,CAQrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACrC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAK3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,UAAU,EACzB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,UAAU,GACf,cAAc,EAAE,CAUlB"}