@panproto/core 0.1.0 → 0.2.0

package/dist/lens.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Lens and combinator API for bidirectional transformations.
+ *
+ * Every migration is a lens with `get` (forward projection) and
+ * `put` (restore from complement). This module provides Cambria-style
+ * combinators that compose into migrations.
+ *
+ * @module
+ */
+/** Rename a field from one name to another. */
+export interface RenameFieldCombinator {
+    readonly type: 'rename-field';
+    readonly old: string;
+    readonly new: string;
+}
+/** Add a new field with a default value. */
+export interface AddFieldCombinator {
+    readonly type: 'add-field';
+    readonly name: string;
+    readonly vertexKind: string;
+    readonly default: unknown;
+}
+/** Remove a field from the schema. */
+export interface RemoveFieldCombinator {
+    readonly type: 'remove-field';
+    readonly name: string;
+}
+/** Wrap a value inside a new object with a given field name. */
+export interface WrapInObjectCombinator {
+    readonly type: 'wrap-in-object';
+    readonly fieldName: string;
+}
+/** Hoist a nested field up to the host level. */
+export interface HoistFieldCombinator {
+    readonly type: 'hoist-field';
+    readonly host: string;
+    readonly field: string;
+}
+/** Coerce a value from one type to another. */
+export interface CoerceTypeCombinator {
+    readonly type: 'coerce-type';
+    readonly fromKind: string;
+    readonly toKind: string;
+}
+/** Sequential composition of two combinators. */
+export interface ComposeCombinator {
+    readonly type: 'compose';
+    readonly first: Combinator;
+    readonly second: Combinator;
+}
+/** A lens combinator (Cambria-style). */
+export type Combinator = RenameFieldCombinator | AddFieldCombinator | RemoveFieldCombinator | WrapInObjectCombinator | HoistFieldCombinator | CoerceTypeCombinator | ComposeCombinator;
+/**
+ * Create a rename-field combinator.
+ *
+ * @param oldName - The current field name
+ * @param newName - The desired field name
+ * @returns A rename-field combinator
+ */
+export declare function renameField(oldName: string, newName: string): RenameFieldCombinator;
+/**
+ * Create an add-field combinator.
+ *
+ * @param name - The field name to add
+ * @param vertexKind - The vertex kind for the new field
+ * @param defaultValue - The default value for the field
+ * @returns An add-field combinator
+ */
+export declare function addField(name: string, vertexKind: string, defaultValue: unknown): AddFieldCombinator;
+/**
+ * Create a remove-field combinator.
+ *
+ * @param name - The field name to remove
+ * @returns A remove-field combinator
+ */
+export declare function removeField(name: string): RemoveFieldCombinator;
+/**
+ * Create a wrap-in-object combinator.
+ *
+ * @param fieldName - The field name for the wrapper object
+ * @returns A wrap-in-object combinator
+ */
+export declare function wrapInObject(fieldName: string): WrapInObjectCombinator;
+/**
+ * Create a hoist-field combinator.
+ *
+ * @param host - The host vertex to hoist into
+ * @param field - The nested field to hoist
+ * @returns A hoist-field combinator
+ */
+export declare function hoistField(host: string, field: string): HoistFieldCombinator;
+/**
+ * Create a coerce-type combinator.
+ *
+ * @param fromKind - The source type kind
+ * @param toKind - The target type kind
+ * @returns A coerce-type combinator
+ */
+export declare function coerceType(fromKind: string, toKind: string): CoerceTypeCombinator;
+/**
+ * Compose two combinators sequentially.
+ *
+ * @param first - The combinator applied first
+ * @param second - The combinator applied second
+ * @returns A composed combinator
+ */
+export declare function compose(first: Combinator, second: Combinator): ComposeCombinator;
+/**
+ * Compose a chain of combinators left-to-right.
+ *
+ * @param combinators - The combinators to compose (at least one required)
+ * @returns The composed combinator
+ * @throws If the combinators array is empty
+ */
+export declare function pipeline(combinators: readonly [Combinator, ...Combinator[]]): Combinator;
+/**
+ * Serialize a combinator to a plain object for MessagePack encoding.
+ *
+ * @param combinator - The combinator to serialize
+ * @returns A plain object suitable for MessagePack encoding
+ */
+export declare function combinatorToWire(combinator: Combinator): Record<string, unknown>;
+//# sourceMappingURL=lens.d.ts.map

package/dist/lens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../src/lens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,sCAAsC;AACtC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAClB,qBAAqB,GACrB,kBAAkB,GAClB,qBAAqB,GACrB,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,CAAC;AAMtB;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAEnF;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,kBAAkB,CAEpG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,sBAAsB,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,oBAAoB,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAEjF;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,iBAAiB,CAEhF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC,GAAG,UAAU,CAGxF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBhF"}

package/dist/migration.d.ts

@@ -0,0 +1,133 @@
+import { WasmModule, Edge, LiftResult, GetResult, ExistenceReport, MigrationSpec } from './types.js';
+import { WasmHandle } from './wasm.js';
+import { BuiltSchema } from './schema.js';
+/**
+ * Fluent builder for constructing migrations between two schemas.
+ *
+ * Each mutation method returns a new `MigrationBuilder` instance,
+ * leaving the original unchanged.
+ *
+ * @example
+ * ```typescript
+ * const migration = panproto.migration(oldSchema, newSchema)
+ *   .map('post', 'post')
+ *   .map('post:body', 'post:body')
+ *   .mapEdge(oldEdge, newEdge)
+ *   .compile();
+ * ```
+ */
+export declare class MigrationBuilder {
+    #private;
+    constructor(src: BuiltSchema, tgt: BuiltSchema, wasm: WasmModule, vertexMap?: ReadonlyMap<string, string>, edgeMap?: readonly [Edge, Edge][], resolvers?: readonly [[string, string], Edge][]);
+    /**
+     * 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: string, tgtVertex: string): MigrationBuilder;
+    /**
+     * 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: Edge, tgtEdge: Edge): MigrationBuilder;
+    /**
+     * 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: string, tgtKind: string, resolvedEdge: Edge): MigrationBuilder;
+    /**
+     * Get the current migration specification.
+     *
+     * @returns The migration spec with all accumulated mappings
+     */
+    toSpec(): MigrationSpec;
+    /**
+     * 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(): CompiledMigration;
+}
+/**
+ * A compiled migration that can efficiently transform records via WASM.
+ *
+ * Implements `Disposable` for automatic cleanup of the WASM resource.
+ */
+export declare class CompiledMigration implements Disposable {
+    #private;
+    constructor(handle: WasmHandle, wasm: WasmModule, spec: MigrationSpec);
+    /** The WASM handle for this migration. Internal use only. */
+    get _handle(): WasmHandle;
+    /** The migration specification used to build this migration. */
+    get spec(): MigrationSpec;
+    /**
+     * 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: unknown): LiftResult;
+    /**
+     * 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: unknown): GetResult;
+    /**
+     * 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: unknown, complement: Uint8Array): LiftResult;
+    /** Release the WASM-side compiled migration resource. */
+    [Symbol.dispose](): void;
+}
+/**
+ * Check existence conditions for a migration between two schemas.
+ *
+ * @param src - Source schema handle
+ * @param tgt - Target schema handle
+ * @param spec - The migration specification
+ * @param wasm - The WASM module
+ * @returns The existence report
+ */
+export declare function checkExistence(protoHandle: number, src: BuiltSchema, tgt: BuiltSchema, spec: MigrationSpec, wasm: WasmModule): ExistenceReport;
+/**
+ * Compose two compiled migrations into a single migration.
+ *
+ * @param m1 - First migration (applied first)
+ * @param m2 - Second migration (applied second)
+ * @param wasm - The WASM module
+ * @returns A new compiled migration representing m2 . m1
+ * @throws {@link MigrationError} if composition fails
+ */
+export declare function composeMigrations(m1: CompiledMigration, m2: CompiledMigration, wasm: WasmModule): CompiledMigration;
+//# sourceMappingURL=migration.d.ts.map

package/dist/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,IAAI,EACJ,UAAU,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;;gBASzB,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,UAAU,EAChB,SAAS,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,EAClD,OAAO,GAAE,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,EAAO,EACrC,SAAS,GAAE,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,EAAO;IAUrD;;;;;;OAMG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAc3D;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,gBAAgB;IAWvD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,gBAAgB;IAW/E;;;;OAIG;IACH,MAAM,IAAI,aAAa;IAQvB;;;;;;;;OAQG;IACH,OAAO,IAAI,iBAAiB;CAqC7B;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,UAAU;;gBAKtC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa;IAMrE,6DAA6D;IAC7D,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,gEAAgE;IAChE,IAAI,IAAI,IAAI,aAAa,CAExB;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU;IAkBjC;;;;;;;;;OASG;IACH,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS;IAuB/B;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,GAAG,UAAU;IAmBtD,yDAAyD;IACzD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,UAAU,GACf,eAAe,CA6BjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,iBAAiB,EACrB,EAAE,EAAE,iBAAiB,EACrB,IAAI,EAAE,UAAU,GACf,iBAAiB,CAgCnB"}

package/dist/msgpack.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MessagePack encode/decode utilities for the WASM boundary.
+ *
+ * All structured data crossing the WASM boundary is serialized as MessagePack
+ * byte slices. This module wraps `@msgpack/msgpack` with typed helpers.
+ *
+ * @module
+ */
+/**
+ * Encode a value to MessagePack bytes for sending to WASM.
+ *
+ * @param value - The value to encode
+ * @returns MessagePack-encoded bytes
+ */
+export declare function packToWasm(value: unknown): Uint8Array;
+/**
+ * Decode MessagePack bytes received from WASM.
+ *
+ * @typeParam T - The expected decoded type
+ * @param bytes - MessagePack-encoded bytes from WASM
+ * @returns The decoded value
+ */
+export declare function unpackFromWasm<T = unknown>(bytes: Uint8Array): T;
+/**
+ * Encode a schema operations list for the `build_schema` entry point.
+ *
+ * @param ops - Array of builder operations
+ * @returns MessagePack-encoded bytes
+ */
+export declare function packSchemaOps(ops: readonly SchemaOp[]): Uint8Array;
+/**
+ * Encode a migration mapping for WASM entry points.
+ *
+ * @param mapping - The migration mapping object
+ * @returns MessagePack-encoded bytes
+ */
+export declare function packMigrationMapping(mapping: MigrationMapping): Uint8Array;
+/**
+ * A single schema builder operation sent to WASM.
+ *
+ * Uses serde internally-tagged format: the `op` field acts as the
+ * discriminant and all variant fields sit at the same level.
+ */
+export interface SchemaOp {
+    readonly op: 'vertex' | 'edge' | 'hyper_edge' | 'constraint' | 'required';
+    readonly [key: string]: unknown;
+}
+/** Wire format for an edge (matches Rust serialization). */
+export interface EdgeWire {
+    readonly src: string;
+    readonly tgt: string;
+    readonly kind: string;
+    readonly name: string | null;
+}
+/** A migration mapping sent to WASM (matches Rust `Migration` struct). */
+export interface MigrationMapping {
+    readonly vertex_map: Record<string, string>;
+    readonly edge_map: Map<EdgeWire, EdgeWire>;
+    readonly hyper_edge_map: Record<string, string>;
+    readonly label_map: Map<readonly [string, string], string>;
+    readonly resolver: Map<readonly [string, string], EdgeWire>;
+}
+//# sourceMappingURL=msgpack.d.ts.map

package/dist/msgpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgpack.d.ts","sourceRoot":"","sources":["../src/msgpack.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,CAAC,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,GAAG,UAAU,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAE1E;AAMD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,UAAU,CAAC;IAC1E,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,4DAA4D;AAC5D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;CAC7D"}

package/dist/panproto.d.ts

@@ -0,0 +1,114 @@
+import { ProtocolSpec, DiffReport } from './types.js';
+import { WasmGlueModule } from './wasm.js';
+import { Protocol } from './protocol.js';
+import { BuiltSchema } from './schema.js';
+import { MigrationBuilder, CompiledMigration } from './migration.js';
+/**
+ * The main entry point for the panproto SDK.
+ *
+ * Create an instance with {@link Panproto.init}, then use it to define
+ * protocols, build schemas, compile migrations, and diff schemas.
+ *
+ * Implements `Disposable` so it can be used with `using` to automatically
+ * clean up all WASM resources.
+ *
+ * @example
+ * ```typescript
+ * const panproto = await Panproto.init();
+ * const atproto = panproto.protocol('atproto');
+ *
+ * const schema = atproto.schema()
+ *   .vertex('post', 'record', { nsid: 'app.bsky.feed.post' })
+ *   .vertex('post:body', 'object')
+ *   .edge('post', 'post:body', 'record-schema')
+ *   .build();
+ *
+ * const migration = panproto.migration(oldSchema, newSchema)
+ *   .map('post', 'post')
+ *   .compile();
+ *
+ * const result = migration.lift(inputRecord);
+ * ```
+ */
+export declare class Panproto implements Disposable {
+    #private;
+    private constructor();
+    /**
+     * Initialize the panproto SDK by loading the WASM module.
+     *
+     * @param input - URL to the wasm-bindgen glue module, or a pre-imported
+     *                glue module object (for bundler environments like Vite).
+     *                Defaults to the bundled glue module.
+     * @returns An initialized Panproto instance
+     * @throws {@link import('./types.js').WasmError} if WASM loading fails
+     */
+    static init(input?: string | URL | WasmGlueModule): Promise<Panproto>;
+    /**
+     * 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: string): Protocol;
+    /**
+     * Define and register a custom protocol.
+     *
+     * @param spec - The protocol specification
+     * @returns The registered protocol
+     * @throws {@link PanprotoError} if registration fails
+     */
+    defineProtocol(spec: ProtocolSpec): Protocol;
+    /**
+     * Start building a migration between two schemas.
+     *
+     * @param src - The source schema
+     * @param tgt - The target schema
+     * @returns A migration builder
+     */
+    migration(src: BuiltSchema, tgt: BuiltSchema): MigrationBuilder;
+    /**
+     * 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: BuiltSchema, tgt: BuiltSchema, builder: MigrationBuilder): import('./types.js').ExistenceReport;
+    /**
+     * 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: CompiledMigration, m2: CompiledMigration): CompiledMigration;
+    /**
+     * 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: BuiltSchema, newSchema: BuiltSchema): DiffReport;
+    /**
+     * Release all WASM resources held by this instance.
+     *
+     * Disposes all cached protocols. After disposal, this instance
+     * must not be used.
+     */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=panproto.d.ts.map

package/dist/panproto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panproto.d.ts","sourceRoot":"","sources":["../src/panproto.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAc,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvE,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EACL,QAAQ,EAGT,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EAGlB,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,QAAS,YAAW,UAAU;;IAIzC,OAAO;IAKP;;;;;;;;OAQG;WACU,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAK3E;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAiBhC;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ;IAM5C;;;;;;OAMG;IACH,SAAS,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,gBAAgB;IAI/D;;;;;;;;;;;OAWG;IACH,cAAc,CACZ,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,YAAY,EAAE,eAAe;IAUvC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,iBAAiB,GAAG,iBAAiB;IAIxE;;;;;;OAMG;IACH,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,GAAG,UAAU;IAQhE;;;;;OAKG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAMzB"}

package/dist/protocol.d.ts

@@ -0,0 +1,65 @@
+import { WasmModule, ProtocolSpec } from './types.js';
+import { WasmHandle } from './wasm.js';
+import { SchemaBuilder } from './schema.js';
+/**
+ * A registered protocol with a WASM-side handle.
+ *
+ * Provides a fluent API for building schemas within this protocol.
+ * Implements `Disposable` for automatic cleanup.
+ */
+export declare class Protocol implements Disposable {
+    #private;
+    constructor(handle: WasmHandle, spec: ProtocolSpec, wasm: WasmModule);
+    /** The protocol name. */
+    get name(): string;
+    /** The full protocol specification. */
+    get spec(): ProtocolSpec;
+    /** The WASM handle. Internal use only. */
+    get _handle(): WasmHandle;
+    /**
+     * Start building a schema within this protocol.
+     *
+     * @returns A new `SchemaBuilder` bound to this protocol
+     */
+    schema(): SchemaBuilder;
+    /** Release the WASM-side protocol resource. */
+    [Symbol.dispose](): void;
+}
+/**
+ * Define a protocol by sending its specification to WASM.
+ *
+ * @param spec - The protocol specification
+ * @param wasm - The WASM module
+ * @returns A registered protocol with a WASM handle
+ * @throws {@link PanprotoError} if the WASM call fails
+ */
+export declare function defineProtocol(spec: ProtocolSpec, wasm: WasmModule): Protocol;
+/**
+ * Built-in ATProto protocol specification.
+ *
+ * Schema theory: colimit(ThGraph, ThConstraint, ThMulti).
+ * Instance theory: ThWType + ThMeta.
+ */
+export declare const ATPROTO_SPEC: ProtocolSpec;
+/**
+ * Built-in SQL protocol specification.
+ *
+ * Schema theory: colimit(ThHypergraph, ThConstraint).
+ * Instance theory: ThFunctor.
+ */
+export declare const SQL_SPEC: ProtocolSpec;
+/**
+ * Built-in Protobuf protocol specification.
+ */
+export declare const PROTOBUF_SPEC: ProtocolSpec;
+/**
+ * Built-in GraphQL protocol specification.
+ */
+export declare const GRAPHQL_SPEC: ProtocolSpec;
+/**
+ * Built-in JSON Schema protocol specification.
+ */
+export declare const JSON_SCHEMA_SPEC: ProtocolSpec;
+/** Registry of built-in protocol specs, keyed by name. */
+export declare const BUILTIN_PROTOCOLS: ReadonlyMap<string, ProtocolSpec>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAY,MAAM,YAAY,CAAC;AAErE,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,QAAS,YAAW,UAAU;;gBAK7B,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU;IAMpE,yBAAyB;IACzB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,uCAAuC;IACvC,IAAI,IAAI,IAAI,YAAY,CAEvB;IAED,0CAA0C;IAC1C,IAAI,OAAO,IAAI,UAAU,CAExB;IAED;;;;OAIG;IACH,MAAM,IAAI,aAAa;IAIvB,+CAA+C;IAC/C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,CAyB7E;AAMD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,YAqB1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,YAWtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,YAW3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,YAY1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAW9B,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAM9D,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,107 @@
+import { WasmModule, Vertex, Edge, HyperEdge, Constraint, VertexOptions, EdgeOptions, SchemaData } from './types.js';
+import { WasmHandle } from './wasm.js';
+import { SchemaOp } from './msgpack.js';
+/**
+ * Immutable fluent builder for constructing schemas.
+ *
+ * Each mutation method returns a new `SchemaBuilder` instance,
+ * leaving the original unchanged. The builder accumulates operations
+ * that are sent to WASM on `.build()`.
+ *
+ * @example
+ * ```typescript
+ * const schema = builder
+ *   .vertex('post', 'record', { nsid: 'app.bsky.feed.post' })
+ *   .vertex('post:body', 'object')
+ *   .edge('post', 'post:body', 'record-schema')
+ *   .build();
+ * ```
+ */
+export declare class SchemaBuilder {
+    #private;
+    constructor(protocolName: string, protocolHandle: WasmHandle, wasm: WasmModule, ops?: readonly SchemaOp[], vertices?: ReadonlyMap<string, Vertex>, edges?: readonly Edge[], hyperEdges?: ReadonlyMap<string, HyperEdge>, constraints?: ReadonlyMap<string, readonly Constraint[]>, required?: ReadonlyMap<string, readonly Edge[]>);
+    /**
+     * 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: string, kind: string, options?: VertexOptions): SchemaBuilder;
+    /**
+     * 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: string, tgt: string, kind: string, options?: EdgeOptions): SchemaBuilder;
+    /**
+     * 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: string, kind: string, signature: Record<string, string>, parentLabel: string): SchemaBuilder;
+    /**
+     * 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: string, sort: string, value: string): SchemaBuilder;
+    /**
+     * 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: string, edges: readonly Edge[]): SchemaBuilder;
+    /**
+     * 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(): BuiltSchema;
+}
+/**
+ * A validated, built schema with a WASM-side handle.
+ *
+ * Implements `Disposable` for automatic cleanup of the WASM resource.
+ */
+export declare class BuiltSchema implements Disposable {
+    #private;
+    constructor(handle: WasmHandle, data: SchemaData, wasm: WasmModule);
+    /** The WASM handle for this schema. Internal use only. */
+    get _handle(): WasmHandle;
+    /** The WASM module reference. Internal use only. */
+    get _wasm(): WasmModule;
+    /** The schema data (vertices, edges, constraints, etc.). */
+    get data(): SchemaData;
+    /** The protocol name this schema belongs to. */
+    get protocol(): string;
+    /** All vertices in the schema. */
+    get vertices(): Readonly<Record<string, Vertex>>;
+    /** All edges in the schema. */
+    get edges(): readonly Edge[];
+    /** Release the WASM-side schema resource. */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,IAAI,EACJ,SAAS,EACT,UAAU,EACV,aAAa,EACb,WAAW,EACX,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG7C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAa;;gBAYtB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,UAAU,EAC1B,IAAI,EAAE,UAAU,EAChB,GAAG,GAAE,SAAS,QAAQ,EAAO,EAC7B,QAAQ,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,EACjD,KAAK,GAAE,SAAS,IAAI,EAAO,EAC3B,UAAU,GAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAa,EACtD,WAAW,GAAE,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAa,EACnE,QAAQ,GAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAa;IAa5D;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa;IAqCxE;;;;;;;;;OASG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa;IA0ClF;;;;;;;;;;OAUG;IACH,SAAS,CACP,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,WAAW,EAAE,MAAM,GAClB,aAAa;IA2BhB;;;;;;;OAOG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa;IA2BxE;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,aAAa;IA6BjE;;;;;;;;OAQG;IACH,KAAK,IAAI,WAAW;CAwBrB;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,UAAU;;gBAKhC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAMlE,0DAA0D;IAC1D,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,oDAAoD;IACpD,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,4DAA4D;IAC5D,IAAI,IAAI,IAAI,UAAU,CAErB;IAED,gDAAgD;IAChD,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,kCAAkC;IAClC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE/C;IAED,+BAA+B;IAC/B,IAAI,KAAK,IAAI,SAAS,IAAI,EAAE,CAE3B;IAED,6CAA6C;IAC7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}