spyret 0.1.0

package/dist/spyret.d.ts

@@ -0,0 +1,746 @@
+import { Graph } from 'graphlib';
+
+type DataInstanceEventType = 'atomAdded' | 'atomRemoved' | 'relationTupleAdded' | 'relationTupleRemoved';
+interface DataInstanceEvent {
+    type: DataInstanceEventType;
+    data: {
+        atom?: IAtom;
+        atomId?: string;
+        relationId?: string;
+        tuple?: ITuple;
+    };
+}
+type DataInstanceEventListener = (event: DataInstanceEvent) => void;
+interface IAtom {
+    id: string;
+    type: string;
+    label: string;
+    /**
+     * Optional key-value labels associated with this atom.
+     * Used for language-specific metadata that should be displayed prominently on nodes
+     * (e.g., Skolems in Alloy, annotations in other languages).
+     * These labels are styled differently from regular attributes - typically in the node's color.
+     */
+    labels?: Record<string, string[]>;
+}
+/**
+ * One tuple in a relation.
+ *
+ * A tuple owns its own arity: `atoms.length` is the truth, and `types` is
+ * this tuple's signature, one entry per atom. A relation may hold tuples of
+ * different arity (see {@link IRelation}), so nothing may read one tuple's
+ * arity as the arity of the relation around it.
+ */
+interface ITuple {
+    atoms: string[];
+    types: string[];
+}
+interface IType {
+    id: string;
+    types: string[];
+    atoms: IAtom[];
+    isBuiltin: boolean;
+}
+/**
+ * A named set of tuples.
+ *
+ * Relations are RAGGED-TOLERANT: the tuples need not all have the same arity.
+ * Host languages hand us this routinely — two unrelated Python classes can both
+ * have a `foo` field, one holding pairs and one holding triples, and both are
+ * the relation `foo`. Alloy reaches the same place from the other side: two
+ * sigs may each declare a field `foo`, and their ids differ (`A<:foo`,
+ * `B<:foo`) while the name does not.
+ *
+ * Records with distinct IDs stay distinct in storage. The name is what
+ * selectors see: a name denotes the set union of all matching records.
+ * IDs are preserved for host reconstruction and exact-ID mutation. Rendering, the
+ * evaluators and the constraint layer all work tuple by tuple, so a ragged
+ * relation draws and queries correctly.
+ */
+interface IRelation {
+    id: string;
+    name: string;
+    /**
+     * A SUMMARY of the tuples' column types, one entry per column, positional.
+     *
+     * It is only meaningful when every tuple has the same arity. When the tuples
+     * disagree — a ragged relation — no positional list can describe them, and
+     * this is `[]`.
+     *
+     * So `types.length` is NOT the relation's arity, and must never be read as
+     * one: on a ragged relation it is 0 no matter how wide the tuples are. Arity
+     * lives on the tuple (`ITuple.atoms.length`).
+     */
+    types: string[];
+    tuples: ITuple[];
+}
+interface IDataInstance {
+    getAtomType(id: string): IType;
+    getTypes(): readonly IType[];
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    generateGraph(hideDisconnected: boolean, hideDisconnectedBuiltIns: boolean): Graph;
+}
+interface IInputDataInstance extends IDataInstance {
+    addAtom(atom: IAtom): void;
+    addRelationTuple(relationId: string, t: ITuple): void;
+    removeAtom(id: string): void;
+    removeRelationTuple(relationId: string, t: ITuple): void;
+    addEventListener(type: DataInstanceEventType, listener: DataInstanceEventListener): void;
+    removeEventListener(type: DataInstanceEventType, listener: DataInstanceEventListener): void;
+    reify(): unknown;
+    /**
+     * Adds atoms and relations from another data instance to this one.
+     * @param dataInstance The data instance to add atoms and relations from.
+     * @param unifyBuiltIns If true, values of built-in types will be unified with existing ones.
+     * @returns true if the data instance was added successfully, false if there were conflicts.
+     */
+    addFromDataInstance(dataInstance: IDataInstance, unifyBuiltIns: boolean): boolean;
+}
+
+/** Spyret's data view of a validated capture, implementing Core's public contract. */
+declare class CapturedDataInstance implements IDataInstance {
+    private datum;
+    private atoms;
+    private types;
+    constructor(datum: {
+        atoms: IAtom[];
+        relations: IRelation[];
+        types: IType[];
+    });
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    getTypes(): readonly IType[];
+    getAtomType(id: string): IType;
+    generateGraph(hideDisconnected?: boolean, hideDisconnectedBuiltIns?: boolean): Graph;
+}
+
+/**
+ * Event plumbing for Spyret's mutable Pyret data instance.
+ *
+ * `emitEvent` is protected: only the instance itself decides when a change
+ * happened. A listener that throws is logged and skipped so one bad listener
+ * cannot starve the others.
+ */
+declare abstract class DataInstanceEventEmitter {
+    private eventListeners;
+    /**
+     * Add an event listener for data instance changes
+     */
+    addEventListener(type: DataInstanceEventType, listener: DataInstanceEventListener): void;
+    /**
+     * Remove an event listener for data instance changes
+     */
+    removeEventListener(type: DataInstanceEventType, listener: DataInstanceEventListener): void;
+    /**
+     * Emit an event to all registered listeners
+     */
+    protected emitEvent(event: DataInstanceEvent): void;
+}
+
+/**
+ * Configuration options for primitive value idempotency in PyretDataInstance
+ */
+interface PyretInstanceOptions {
+    /** Whether to make string values idempotent (reuse atoms for same string values) */
+    stringsIdempotent?: boolean;
+    /** Whether to make number values idempotent (reuse atoms for same number values) */
+    numbersIdempotent?: boolean;
+    /** Whether to make boolean values idempotent (reuse atoms for same boolean values) */
+    booleansIdempotent?: boolean;
+    /** Whether to include function/method fields in parsing */
+    showFunctions?: boolean;
+}
+/**
+ * Result of evaluating a Pyret expression
+ */
+interface PyretEvaluationResult {
+    /** The raw Pyret JS value (if successful) */
+    result?: unknown;
+    /** Exception information (if failed) */
+    exn?: unknown;
+    /** Whether the evaluation was successful */
+    success?: boolean;
+}
+/**
+ * An external Pyret evaluator — in practice `window.__internalRepl`, which the
+ * Pyret IDE installs.
+ *
+ * This lived in the REPL's expression parser until that component was removed,
+ * but it was never a REPL type: it describes the runtime a `PyretDataInstance`
+ * evaluates against, which is why `fromExpression` and `setExternalEvaluator`
+ * take one. It sits here now, next to the result type it returns — which this
+ * file had already redeclared privately rather than import across that
+ * boundary.
+ */
+interface PyretEvaluator {
+    /**
+     * Run a Pyret expression and return the result
+     * @param code - Pyret code to evaluate
+     * @param sourceLocation - Optional source location identifier
+     * @returns Promise that resolves to evaluation result
+     */
+    run(code: string, sourceLocation?: string): Promise<PyretEvaluationResult>;
+    /**
+     * Runtime utilities for checking result types
+     */
+    runtime: {
+        isSuccessResult(result: PyretEvaluationResult): boolean;
+    };
+}
+/** Global constructor cache entry with pattern and instantiation priority */
+interface ConstructorCacheEntry {
+    pattern: string[];
+    instantiation: number;
+}
+declare function generateEdgeId(relation: IRelation, tuple: ITuple): string;
+/**
+ * Pyret data instance implementation for parsing Pyret runtime objects
+ *
+ * Handles Pyret's object representation where:
+ * - Objects have a `dict` property containing field values
+ * - Objects have a `brands` property indicating their type
+ * - All dict entries are treated as relations
+ * - Pyret tables are parsed as semantic relations: each row becomes an n-ary tuple
+ * - Non-table arrays are parsed as relations with Array atoms
+ * - Nested arrays are supported with intermediate Array atoms
+ * - Cycles are handled gracefully without infinite recursion
+ * - Primitive idempotency is configurable via constructor options
+ *
+ * @example
+ * ```typescript
+ * // Tree data
+ * const pyretData = {
+ *   dict: { value: 11, left: {...}, right: {...} },
+ *   brands: { "$brandtnode989": true }
+ * };
+ * const instance1 = new PyretDataInstance(pyretData);
+ *
+ * // Table data - creates semantic relational tuples
+ * const tableData = {
+ *   dict: {
+ *     r: {
+ *       dict: {
+ *         "_header-raw-array": ["origin", "destination"],
+ *         "_rows-raw-array": [["PVD", "ORD"], ["ORD", "PVD"]]
+ *       },
+ *       brands: { "$brandtable168": true }
+ *     }
+ *   }
+ * };
+ * const instance2 = new PyretDataInstance(tableData);
+ * // Creates column(table, index, name) and row(table, index, ...cells).
+ * // Project with Index.(Table.row) for the cell-only (PVD, ORD), (ORD, PVD) view.
+ *
+ * // Custom idempotency settings
+ * const instance3 = new PyretDataInstance(pyretData, {
+ *   stringsIdempotent: false,  // Different string instances won't be unified
+ *   numbersIdempotent: true,   // Same numbers will be unified
+ *   booleansIdempotent: true   // Same booleans will be unified
+ * });
+ * ```
+ */
+declare class PyretDataInstance extends DataInstanceEventEmitter implements IInputDataInstance {
+    /** Capture normalized roots together so aliases across roots retain one atom. */
+    static fromValues(values: readonly unknown[]): {
+        instance: PyretDataInstance;
+        rootIds: string[];
+    };
+    private atoms;
+    private relations;
+    private types;
+    private objectToAtomId;
+    private atomCounter;
+    /** Opaque relation identities; their names and tuples carry the semantics. */
+    private valueRelations;
+    private indexAtoms;
+    /** Map to keep track of label counts per type */
+    private typeLabelCounters;
+    /** Map to store the original Pyret objects with their dict key order */
+    private originalObjects;
+    /** Configuration options for primitive handling */
+    private readonly options;
+    /** Global map to store constructor patterns and field order for types across all instances */
+    private static globalConstructorCache;
+    /** Global counter for instantiation priority - higher numbers mean newer/higher priority */
+    private static instantiationCounter;
+    /** Optional external Pyret evaluator for enhanced features */
+    private externalEvaluator;
+    /**
+     * Creates a PyretDataInstance from a Pyret runtime object
+     *
+     * @param pyretData - The root Pyret object to parse, or null/undefined for an empty instance
+     * @param options - Configuration options for primitive handling and other behaviors
+     * @param externalEvaluator - Optional external Pyret evaluator for enhanced features
+     */
+    constructor(pyretData?: PyretObject | unknown[] | number | string | boolean | null, options?: PyretInstanceOptions, externalEvaluator?: any);
+    /**
+     * Set an external Pyret evaluator for enhanced features
+     * @param evaluator - External Pyret evaluator (e.g., window.__internalRepl)
+     */
+    setExternalEvaluator(evaluator: any): void;
+    /**
+     * Get the current external evaluator
+     */
+    getExternalEvaluator(): any | null;
+    /**
+     * Get the current primitive idempotency configuration
+     */
+    getOptions(): Required<PyretInstanceOptions>;
+    /**
+     * Cache constructor field order for a type when we successfully parse an original object
+     * This now uses a global cache with instantiation-based priority where newer patterns
+     * can override older ones for the same constructor name
+     */
+    private cacheConstructorPattern;
+    /**
+     * Get the global constructor cache (for debugging or advanced use cases)
+     * Returns a map of type names to their patterns
+     */
+    static getGlobalConstructorCache(): Map<string, string[]>;
+    /**
+     * Get the global constructor cache with instantiation info (for debugging)
+     * Returns the raw cache with instantiation numbers
+     */
+    static getGlobalConstructorCacheWithPriority(): Map<string, ConstructorCacheEntry>;
+    /**
+     * Clear the global constructor cache (for testing or reset scenarios)
+     */
+    static clearGlobalConstructorCache(): void;
+    /**
+     * Creates a PyretDataInstance from a Pyret expression.
+     *
+     * @param expr - The Pyret expression to evaluate.
+     * @param options - Configuration options for primitive handling and other behaviors
+     * @param externalEvaluator - External Pyret evaluator with a `run` method for enhanced features.
+     * @returns A new PyretDataInstance created from the evaluated expression.
+     * @throws {Error} If the expression cannot be evaluated or parsed.
+     */
+    static fromExpression(expr: string, options: PyretInstanceOptions | undefined, externalEvaluator: {
+        run: (code: string) => Promise<unknown>;
+    }): Promise<PyretDataInstance>;
+    /**
+     * Evaluates a Pyret expression using an external evaluator
+     *
+     * @param expr - The Pyret expression to evaluate
+     * @param externalEvaluator - External Pyret evaluator with a `run` method
+     * @returns Promise resolving to evaluation result
+     */
+    private static evaluateExpression;
+    /**
+     * Recursively searches for a key at any level in an object
+     */
+    private static findKeyAtAnyLevel;
+    /**
+     * Checks if a value is a primitive type (string, number, boolean)
+     */
+    private static isPrimitive;
+    /**
+     * Format Pyret evaluation errors for display
+     */
+    private static formatError;
+    hasExternalEvaluator(): boolean;
+    /**
+     * Adds an atom to the instance, updating types accordingly.
+     * If the atom already exists, it is replaced.
+     * @param atom - The atom to add
+     */
+    addAtom(atom: IAtom): void;
+    /**
+     * Removes an atom by id, and removes it from all types and relations.
+     * @param id - The atom id to remove
+     */
+    removeAtom(id: string): void;
+    removeRelationTuple(relationId: string, t: ITuple): void;
+    /**
+     * Converts the current data instance back to Pyret constructor notation
+     *
+     * This is the REPL-equivalent string form: the value is first reconstructed
+     * from the relations (`reifyToValue`, which memoizes by atom id so a shared
+     * atom becomes one shared object and a cycle becomes a real back-reference),
+     * then rendered (`replit`). Supported reference graphs emit bindings and
+     * mutable-field updates. The legacy ref-free path repeats shared subtrees
+     * and prints a `<cyclic>` marker for synthetic object cycles.
+     *
+     * @param rootId Atom to reconstruct. Required when no unique root can be inferred,
+     * including a fully cyclic graph. The datum does not store an observation point.
+     * @returns A string representation of the data in Pyret constructor syntax
+     *
+     * @example
+     * ```typescript
+     * const pyretCode = instance.reify();
+     * ```
+     */
+    reify(rootId?: string): string;
+    /**
+     * Parses Pyret objects iteratively to avoid stack overflow and handle cycles
+     */
+    private parseObjectIteratively;
+    private addValueFact;
+    private valueRelationId;
+    private createIndexAtom;
+    private valueInfo;
+    /** One ordered header relation and one row relation per width; IDs stay opaque. */
+    private processTableSemantics;
+    /**
+     * Creates an atom from a Pyret object and stores the mapping
+     */
+    private createAtomFromObject;
+    /**
+     * Creates an atom from a primitive value, optionally reusing existing atoms based on configuration
+     */
+    private createAtomFromPrimitive;
+    /**
+     * Maps JavaScript primitive types to Pyret-appropriate type names
+     */
+    private mapPrimitiveType;
+    /**
+     * Extracts the most specific brand name from a Pyret brands object.
+     * Returns the brand with the highest trailing number, with prefix and number removed.
+     * If no brands have trailing numbers, returns the lexicographically last brand.
+     *
+     * @param brands - The brands object from a Pyret object
+     * @returns The most specific brand name (without $brand and trailing number), or undefined if none found
+     */
+    private extractMostSpecificBrand;
+    /**
+     * Extracts the type name from a Pyret object
+     */
+    private extractType;
+    /**
+     * Extracts a display label from a Pyret object, using a per-type counter.
+     * Labels will be of the form Type$<num>
+     */
+    private extractLabel;
+    /**
+     * Adds a tuple to a relation, creating the relation if it doesn't exist
+     */
+    addRelationTuple(relationId: string, tuple: ITuple, relationName?: string): void;
+    /**
+     * Ensures a type exists in the types map
+     */
+    private ensureTypeExists;
+    /**
+     * Initializes common builtin types
+     */
+    private initializeBuiltinTypes;
+    /**
+     * Checks if a type is a builtin type
+     */
+    private isBuiltinType;
+    /** Primitive JS values, runtime numeric objects, and structural numeric carriers. */
+    private isAtomicValue;
+    /**
+     * Type guard for Pyret objects
+     */
+    private isPyretObject;
+    /**
+     * Generates a unique atom ID
+     */
+    private generateAtomId;
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    getTypes(): readonly IType[];
+    getAtomType(atomId: string): IType;
+    /**
+     * Generates a graphlib Graph representation of this data instance.
+     *
+     * This method creates a directed multigraph where:
+     * - Each atom becomes a node with its label and type as metadata
+     * - Each relation tuple becomes an edge between atoms
+     * - Multi-atom tuples (arity > 2) are handled by connecting first to last atom
+     * - Disconnected nodes can be optionally filtered out
+     *
+     * @param hideDisconnected - Whether to hide atoms with no relations
+     * @param hideDisconnectedBuiltIns - Whether to hide disconnected built-in types
+     * @returns A graphlib Graph object ready for layout algorithms
+     *
+     * @example
+     * ```typescript
+     * const graph = instance.generateGraph(true, true);
+     * // Use with WebCola or other layout algorithms
+     * const layout = new cola.Layout().nodes(graph.nodes()).edges(graph.edges());
+     * ```
+     */
+    generateGraph(hideDisconnected?: boolean, hideDisconnectedBuiltIns?: boolean): Graph;
+    /**
+     * Adds a PyretDataInstance to this instance, optionally unifying built-in types
+     *
+     * @param dataInstance - The PyretDataInstance to add
+     * @param unifyBuiltIns - Whether to unify built-in atoms
+     * @returns True if the instance was added successfully, false otherwise
+     */
+    addFromDataInstance(dataInstance: IDataInstance, unifyBuiltIns: boolean): boolean;
+}
+/**
+ * Type definitions for Pyret runtime objects
+ */
+interface PyretObject {
+    dict?: Record<string, unknown>;
+    brands?: Record<string, boolean>;
+    $name?: string;
+    $loc?: unknown[];
+    $mut_fields_mask?: unknown[];
+    $arity?: number;
+    $constructor?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Factory function to create PyretDataInstance from JSON string
+ *
+ * @param jsonString - JSON representation of a Pyret object
+ * @param options - Configuration options for primitive handling and other behaviors
+ * @returns New PyretDataInstance
+ *
+ * @example
+ * ```typescript
+ * const jsonData = '{"dict": {"value": 42}, "brands": {"$brandleaf": true}}';
+ * const instance = createPyretDataInstance(jsonData, { stringsIdempotent: false });
+ * ```
+ */
+declare const createPyretDataInstance: (jsonString: string, options?: PyretInstanceOptions) => PyretDataInstance;
+/**
+ * Type guard to check if an IInputDataInstance is a PyretDataInstance
+ *
+ * @param instance - IInputDataInstance to check
+ * @returns True if the instance is a PyretDataInstance
+ */
+declare const isPyretDataInstance: (instance: IInputDataInstance) => instance is PyretDataInstance;
+
+/** Internal lossless numbers. IDataInstance stores their literal in the atom label. */
+type PyretNumberPayload = {
+    version: 1;
+} & ({
+    kind: 'integer';
+    value: string;
+} | {
+    kind: 'rational';
+    numerator: string;
+    denominator: string;
+} | {
+    kind: 'roughnum';
+    value: string;
+});
+/** Structural reification uses this carrier without requiring a live runtime. */
+interface ReifiedNumber {
+    $pyretNumber: PyretNumberPayload;
+}
+
+/**
+ * Structural reify for PyretDataInstance.
+ *
+ * This is the *inverse of relationalization*: given a data instance (atoms +
+ * relations only — NO live Pyret value, NO runtime), reconstruct a value.
+ *
+ * The key design choice (see the fidelity design notes): reify reconstructs a
+ * **synthetic `PyretObject`** — the exact `{ dict, brands/$name }` shape that
+ * `PyretDataInstance.parseObjectIteratively` already consumes. That makes the
+ * round-trip self-contained: we can feed the reified value straight back into
+ * `new PyretDataInstance(...)` and compare, with no Pyret runtime in the loop.
+ *
+ * Sharing and cycles are carried by **real JS object identity** in the
+ * reconstructed graph (a memo keyed by atom id), so a shared atom becomes one
+ * shared JS object and a cyclic atom becomes a real JS back-reference — exactly
+ * mirroring how the relationalizer's `WeakMap` captured them in the first place.
+ *
+ * NOTE: this is a *structural* reify (the analog of Python's live-object
+ * `reify`). The string form (the analog of Python's `repl`/`repr(reify(...))`)
+ * is `replit` in ./replit.ts.
+ */
+
+/** A reconstructed value, independent of a live Pyret runtime. */
+type ReifiedValue = ReifiedNumber | PyretObject | ReifiedValue[] | number | string | boolean | null;
+/**
+ * Reconstruct a value from a data instance.
+ *
+ * @param di      the data instance (atoms + relations)
+ * @param rootId  atom to reconstruct; otherwise requires exactly one atom with
+ *                no incoming tuples. Cycles and multiple roots require this argument.
+ * @returns a synthetic, re-relationalizable value (PyretObject / array / primitive)
+ */
+declare function reifyToValue(di: IDataInstance, rootId?: string, options?: {
+    allowContainerCycles?: boolean;
+}): ReifiedValue;
+/** Reconstruct roots with a common identity memo, including cross-root aliases. */
+declare function reifyToValues(di: IDataInstance, rootIds?: readonly string[], options?: {
+    allowContainerCycles?: boolean;
+}): ReifiedValue[];
+
+declare function readConstructorTypeId(id: string): {
+    scope: string;
+    index: number;
+    name: string;
+} | undefined;
+declare function constructorDisplayName(id: string): string;
+interface ConstructorInfo {
+    name: string;
+    arity: number;
+    fields: string[];
+    mutableFields?: number[];
+}
+
+/** The adapter returns observations, never serialized values or display output. */
+type PyretObservation = {
+    kind: 'primitive';
+    value: string | boolean | {
+        $pyretNumber: PyretNumberPayload;
+    };
+} | {
+    kind: 'nothing';
+} | {
+    kind: 'constructor';
+    identity: object;
+    info: ConstructorInfo;
+    values: unknown[];
+} | {
+    kind: 'object';
+    fields: Array<[string, unknown]>;
+} | {
+    kind: 'raw-array' | 'tuple';
+    values: unknown[];
+} | {
+    kind: 'reference';
+    value: unknown;
+} | {
+    kind: 'string-dict';
+    mutable: boolean;
+    sealed: boolean;
+    entries: Array<[string, unknown]>;
+} | {
+    kind: 'table';
+    headers: string[];
+    rows: unknown[][];
+};
+interface PyretRuntimeAdapter {
+    /** Throw for unsupported state; capture adds the selected root and path. */
+    observe(value: unknown): PyretObservation;
+}
+/** Predicates must come from the runtime that owns the value, not another realm. */
+interface PyretCaptureRuntime {
+    Any: unknown;
+    isNumber(value: unknown): boolean;
+    isNothing(value: unknown): boolean;
+    isDataValue(value: unknown): boolean;
+    isTuple(value: unknown): boolean;
+    isRef(value: unknown): boolean;
+    isFunction(value: unknown): boolean;
+    isMethod(value: unknown): boolean;
+    isOpaque(value: unknown): boolean;
+    isObject(value: unknown): boolean;
+}
+/**
+ * Adapter for upstream Pyret's JS runtime. All runtime representation reads are
+ * isolated here (including library backing stores). No printers, annotations,
+ * user functions, field dereferencing, or evaluator operations are invoked.
+ */
+declare function createPyretRuntimeAdapter(runtime: PyretCaptureRuntime): PyretRuntimeAdapter;
+
+type PyretCaptureJson = null | boolean | number | string | PyretCaptureJson[] | {
+    [key: string]: PyretCaptureJson;
+};
+interface PyretCaptureRoot {
+    name: string;
+    value: unknown;
+    observation?: PyretCaptureJson;
+}
+interface PyretCaptureSnapshot {
+    format: 'spytial-pyret-capture';
+    version: 1;
+    datum: {
+        atoms: IAtom[];
+        relations: IRelation[];
+        types: IType[];
+    };
+    roots: Array<{
+        name: string;
+        atomId: string;
+        observation?: PyretCaptureJson;
+    }>;
+    provenance?: PyretCaptureJson;
+}
+declare class PyretCaptureError extends Error {
+    readonly root: string;
+    readonly path: readonly (string | number)[];
+    readonly reason: string;
+    constructor(root: string, path: readonly (string | number)[], reason: string);
+}
+/**
+ * Snapshot declared state without running user code. Adapter observations are
+ * materialized as transient structural carriers for the existing relationalizer;
+ * only its datum is exported. The carriers and all live identities die here.
+ */
+declare function capturePyret(roots: readonly PyretCaptureRoot[], adapter: PyretRuntimeAdapter, provenance?: PyretCaptureJson): PyretCaptureSnapshot;
+/** Import with no runtime, producer caches, browser or evaluator. Never repair invalid capture data. */
+declare function importPyretCapture(input: unknown): {
+    snapshot: PyretCaptureSnapshot;
+    instance: CapturedDataInstance;
+    values: ReadonlyMap<string, ReifiedValue>;
+};
+
+/**
+ * replit — the REPL-equivalent string form of a reified value.
+ *
+ * The Pyret analog of Python's `repr(reify(...))` / Rust's
+ * `format!("{:?}", from_datum(...))`: reconstruct the value (./reify.ts), then
+ * render it to the source/REPL string a programmer would read.
+ *
+ * Rendering rules:
+ *   - primitives:     5     "hi"    true     nothing
+ *   - raw arrays:     [raw-array: a, b, c]
+ *   - tuples:         {a; b}
+ *   - built-in sets:  public collection syntax (list-set adds preserve order)
+ *   - dictionaries:  public collection syntax (include string-dict at evaluation)
+ *   - tables:        table literals / public constructors (include tables at evaluation)
+ *   - plain objects:  {field: value}
+ *   - data variants:  type(field0, field1, ...)   (fields in reconstructed order)
+ *
+ * Field ORDER here comes from the reconstructed object's dict order, which reify
+ * takes from serialized field IDs for v6 constructor data. Only legacy data
+ * falls back to the constructor cache / alphabetical field order.
+ *
+ * References, shared mutable dictionaries, and shared table cells use bindings and updates to
+ * preserve sharing/cycles (see reference-source.ts for the construction subset).
+ * The legacy ref-free renderer repeats DAGs and emits a `<cyclic>` marker for
+ * synthetic object cycles, which are not claimed as evaluable Pyret source.
+ */
+
+/** Reconstruct and render the selected atom; infer it only when there is a unique root. */
+declare function replit(di: IDataInstance, rootId?: string): string;
+
+/** Convert a value owned by this runtime into Core's IDataInstance contract. */
+declare function toDataInstance(value: unknown, runtime: Parameters<typeof createPyretRuntimeAdapter>[0]): IDataInstance;
+/** The Pyret-specific part of diagramming. Rendering is supplied by the host. */
+declare function prepareDiagram(value: unknown, runtime: Parameters<typeof createPyretRuntimeAdapter>[0]): {
+    snapshot: PyretCaptureSnapshot;
+    instance: CapturedDataInstance;
+    sourcePreview: string;
+};
+/** Format a presentation copy only, after selector and layout evaluation. */
+declare function diagramTypeNames<N extends {
+    mostSpecificType: string;
+}, L extends {
+    nodes: N[];
+}>(layout: L): L;
+
+/**
+ * Canonicalization of a data instance.
+ *
+ * Atom ids (`tno_3`, `num_7`, ...) are arbitrary gensyms, so two instances that
+ * are equal *up to renaming* must be made byte-identical before comparison.
+ * `canon` produces a stable string with:
+ *   - atom ids renamed to integers via a deterministic traversal from the roots,
+ *   - primitive atoms keyed by (type, label) — the label IS the data and is kept;
+ *     structured atoms retain type; their display labels are dropped,
+ *   - relations keyed by name; constructor fields retain their semantic IDs,
+ *     with tuples sorted lexicographically.
+ *
+ * v6 constructor field IDs include position. Canon preserves those IDs. Legacy
+ * fields retain only names; canonicalizing cannot recover their argument order.
+ *
+ * This is the substrate for the self-contained (Tier A) fidelity oracles
+ * (see tests/pyret/oracles.ts).
+ */
+
+declare function canon(di: IDataInstance, rootId?: string): string;
+
+export { PyretCaptureError, type PyretCaptureJson, type PyretCaptureRoot, type PyretCaptureRuntime, type PyretCaptureSnapshot, PyretDataInstance, type PyretEvaluationResult, type PyretEvaluator, type PyretInstanceOptions, type PyretObject, type PyretObservation, type PyretRuntimeAdapter, type ReifiedValue, canon, capturePyret, constructorDisplayName, createPyretDataInstance, createPyretRuntimeAdapter, diagramTypeNames, generateEdgeId, importPyretCapture, isPyretDataInstance, prepareDiagram, replit as pyretCaptureSource, readConstructorTypeId, reifyToValue, reifyToValues, replit, toDataInstance };