Flipped EnvMap as the default.

Author: uhop

AGENTS.md

@@ -71,7 +71,7 @@ deep6/
 │   └── utils/
 │       └── replaceVars.js   # Variable replacement utility
 ├── tests/                # Test files
-│   ├── tests.js          # Test dispatcher (~706 tests)
+│   ├── tests.js          # Test dispatcher (~705 tests)
 │   ├── harness.js        # Shared test harness
 │   ├── test-*.js         # Test groups (env, env-map, unify, match, registry, unifiers, traverse, index, edge-cases)
 │   └── server.js         # Browser test server
@@ -103,8 +103,8 @@ deep6/
   - Support open/soft object matching
 
 - **Environment** — two interchangeable implementations of the `EnvLike` method contract:
-  - `Env` (`src/env.js`) — proto-chain implementation; the default created by `unify()` when no env is passed.
-  - `EnvMap` (`src/env-map.js`) — `Map`-stack sibling; ~4–8× faster on accumulating-symbol/alias workloads (solver-style use). Opt in by passing `new EnvMap()` to `unify()`.
+  - `EnvMap` (`src/env-map.js`) — `Map`-stack implementation; the default created by `unify()` when no env is passed. ~4–8× faster on accumulating-symbol/alias workloads (solver-style use).
+  - `Env` (`src/env.js`) — proto-chain sibling; opt in by passing `new Env()` to `unify()`.
   - Behavioural flags (`openObjects`, `circular`, `symbols`, …) live on `env.options` — never on the env instance directly.
   - `EnvLike` (`src/env-shared.d.ts`, TS-only) — the method contract both classes implement.
 - **Shared primitives** (`src/env-shared.js`) — implementation-agnostic, work with any `EnvLike`:
@@ -232,7 +232,7 @@ clone.registry.push(MyClass, (val, context) => /* clone */);
 
 - **Zero dependencies.** Do not add runtime dependencies.
 - All public API is in `src/`.
-- Tests verify correctness against ~706 assertions.
+- Tests verify correctness against ~705 assertions.
 - The project supports modern environments: Node.js, browsers, Deno, Bun.
 
 ## When reading the codebase
@@ -248,7 +248,7 @@ clone.registry.push(MyClass, (val, context) => /* clone */);
 
 - `src/unify.js` — Core unification algorithm (non-recursive stack-based)
 - `src/env-shared.js` — Implementation-agnostic primitives: Unifier, Variable, any/\_
-- `src/env.js` — Default proto-chain `Env` implementation
-- `src/env-map.js` — Map-stack `EnvMap` sibling (perf opt-in for solver workloads)
+- `src/env-map.js` — Map-stack `EnvMap` implementation (the default)
+- `src/env.js` — Proto-chain `Env` sibling (opt-in)
 - `src/traverse/walk.js` — Foundation for all traversal operations
 - `src/index.js` — Main entry point and public API

ARCHITECTURE.md

@@ -54,8 +54,8 @@ The main unification loop (the `unify` function in `src/unify.js`) processes pai
 
 A unification environment carries variable bindings and a stack of generation frames so the solver can backtrack. Two interchangeable implementations conform to the `EnvLike` method contract:
 
-- **`Env`** (`src/env.js`) — the default. Two parallel `null`-prototype objects walked through `Object.create()` chains; one frame per `push()`. Cheap for shallow workloads, pays a dict-mode-deopt tax once enough symbol-named bindings accumulate.
-- **`EnvMap`** (`src/env-map.js`) — a sibling implementation. Two parallel `Map`-stacks (one entry per depth, lazily allocated). Identity-hashed lookup avoids the deopt; measures 4–8× faster on accumulating-symbol / alias-binding workloads (typical of solver-style consumers).
+- **`EnvMap`** (`src/env-map.js`) — the default. Two parallel `Map`-stacks (one entry per depth, lazily allocated). Identity-hashed lookup avoids dict-mode deopts; measures 4–8× faster on accumulating-symbol / alias-binding workloads (typical of solver-style consumers).
+- **`Env`** (`src/env.js`) — a sibling implementation. Two parallel `null`-prototype objects walked through `Object.create()` chains; one frame per `push()`. Cheap for shallow workloads, pays a dict-mode-deopt tax once enough symbol-named bindings accumulate.
 
 Both classes expose the same methods (`push`/`pop`/`revert`/`bindVar`/`bindVal`/`isBound`/`isAlias`/`get`/`getAllValues`) and the same public `depth` and `options` fields. Behavioural flags (`openObjects`, `circular`, `symbols`, etc.) live on `env.options` — `unify()` merges any per-call options into that bag, so chaining accumulates.
 
@@ -157,7 +157,7 @@ src/unifiers/ref.js ── src/env.js (Unifier, isVariable)
 src/utils/replaceVars.js ── src/env.js (isVariable)
 ```
 
-Both `src/env.js` and `src/env-map.js` re-export the full shared surface so callers can keep using `import {...} from 'deep6/env.js'` for the proto-chain default, or import directly from `deep6/env-map.js` (which doubles as a single import point covering EnvMap + the shared primitives) for the Map-stack alternative.
+Both `src/env.js` and `src/env-map.js` re-export the full shared surface so callers can keep using `import {...} from 'deep6/env.js'` for the proto-chain sibling, or import directly from `deep6/env-map.js` (which doubles as a single import point covering EnvMap + the shared primitives) for the Map-stack default.
 
 ## Import paths
 
@@ -168,13 +168,13 @@ import {equal, clone, match, any} from 'deep6';
 // Core unification
 import {unify, Variable, variable, Unifier, any, _} from 'deep6/unify.js';
 
-// Environment (proto-chain — default)
+// Environment (Map-stack — default)
+import {EnvMap} from 'deep6/env-map.js';
+
+// Environment (proto-chain — opt in)
 import {Env, Variable, Unifier, any, _} from 'deep6/env.js';
 import type {EnvLike} from 'deep6/env.js';
 
-// Environment (Map-stack sibling — opt in)
-import {EnvMap} from 'deep6/env-map.js';
-
 // Implementation-agnostic primitives (also re-exported by env.js / env-map.js)
 import {Unifier, Variable, variable, isUnifier, isVariable, _, any} from 'deep6/env-shared.js';
 

CODEBASE.md

@@ -89,7 +89,7 @@ src/
 
 ## Testing
 
-- **Files:** `tests/test-*.js` (~706 assertions), dispatched by `tests/tests.js`
+- **Files:** `tests/test-*.js` (~705 assertions), dispatched by `tests/tests.js`
 - **Run:** `npm test`
 - **Debug:** `npm run debug` (Node inspector)
 - **Browser:** `npm start` (opens test server)

llms-full.txt

@@ -141,12 +141,12 @@ v.get(env);        // 2
 Two interchangeable environment implementations conform to the `EnvLike` contract; either can be passed to `unify()` as its third argument.
 
 ```js
-import {Env} from 'deep6/env.js';            // proto-chain (default)
-import {EnvMap} from 'deep6/env-map.js';     // Map-stack (4–8× faster on
-                                             // accumulating-symbol workloads)
+import {EnvMap} from 'deep6/env-map.js';     // Map-stack (default; 4–8× faster
+                                             // on accumulating-symbol workloads)
+import {Env} from 'deep6/env.js';            // proto-chain (opt-in sibling)
 import type {EnvLike} from 'deep6/env.js';   // method contract (TS only)
 
-const env = new Env();    // or new EnvMap();
+const env = new EnvMap();    // or new Env();
 // public surface (identical across implementations):
 //   env.depth                                  number, generation counter
 //   env.options                                bag of unify() flags

llms.txt

@@ -90,15 +90,15 @@ The third argument can be either an environment instance or an options bag — `
 
 Two interchangeable implementations of the `EnvLike` contract:
 
-- `Env` (`deep6/env.js`) — proto-chain, the default created when no env is passed.
-- `EnvMap` (`deep6/env-map.js`) — `Map`-stack sibling; ~4–8× faster on accumulating-symbol/alias workloads (solver-style use). Opt in by passing `new EnvMap()` to `unify()`.
+- `EnvMap` (`deep6/env-map.js`) — `Map`-stack, the default created when no env is passed; ~4–8× faster on accumulating-symbol/alias workloads (solver-style use).
+- `Env` (`deep6/env.js`) — proto-chain sibling; opt in by passing `new Env()` to `unify()`.
 
 ```js
 import {unify, variable} from 'deep6/unify.js';
-import {EnvMap} from 'deep6/env-map.js';
+import {Env} from 'deep6/env.js';
 
 const x = variable('x');
-const env = unify({a: x}, {a: 1}, new EnvMap());
+const env = unify({a: x}, {a: 1}, new Env());
 // x.get(env) === 1
 ```
 

src/unify.d.ts

@@ -1,7 +1,7 @@
 // Type definitions for deep6 unification
 // Generated from src/unify.js
 
-import {Env} from './env.js';
+import type {EnvLike} from './env.js';
 
 /**
  * Options for unification
@@ -37,7 +37,9 @@ export interface UnifyOptions {
  * Core unification algorithm
  *
  * Attempts to unify two values, optionally binding variables.
- * Returns an Env with bindings on success, or null on failure.
+ * Returns the environment with bindings on success (the one passed in, or a
+ * new `EnvMap` — the default implementation — when none was given), or null
+ * on failure.
  *
  * `unify.registry` is a flat array of type-specific unifier pairs:
  * `[Constructor, handler, Constructor, handler, ...]`. Push pairs to
@@ -54,7 +56,7 @@ export interface UnifyOptions {
  * @param options - Unification options (when env is provided separately)
  * @returns Environment with bindings, or null on failure
  */
-export declare const unify: ((l: unknown, r: unknown, env?: Env | UnifyOptions | null, options?: UnifyOptions) => Env | null) & {
+export declare const unify: ((l: unknown, r: unknown, env?: EnvLike | UnifyOptions | null, options?: UnifyOptions) => EnvLike | null) & {
   registry: unknown[];
   filters: unknown[];
 };
@@ -109,8 +111,7 @@ export declare const isSoft: (o: unknown) => boolean;
  */
 export declare const isWrapped: (o: unknown) => boolean;
 
-// Re-exports from env.js (value exports, usable as constructors)
-export {Env, Unifier, Variable} from './env.js';
-export {_, any, isUnifier, isVariable, variable} from './env.js';
+// Re-exports from env.js (values usable as constructors, plus the EnvLike contract)
+export {Env, Unifier, Variable, _, any, isUnifier, isVariable, variable, type EnvLike} from './env.js';
 
 export default unify;

src/unify.js

@@ -1,5 +1,6 @@
 // @ts-self-types="./unify.d.ts"
 import {_, Env, Variable, variable, isVariable, Unifier, isUnifier} from './env.js';
+import {EnvMap} from './env-map.js';
 
 // Command
 
@@ -434,7 +435,7 @@ const unify = (l, r, env, options) => {
     env = null;
   }
   if (!env) {
-    env = new Env();
+    env = new EnvMap();
   }
   env.options = options ? {...env.options, ...options} : env.options;
   // options: openObjects, openArrays, openMaps, openSets, circular, loose, ignoreFunctions, signedZero, symbols.

tests/test-unify.js

@@ -61,37 +61,41 @@ export default [
     eval(TEST('!unify({a: {a: 1}, b: 2}, {a: {a: 1}, b: 3})'));
   },
   function test_variables() {
+    const values = env => {
+      const all = {};
+      for (const {name, value} of env.getAllValues()) all[name] = value;
+      return all;
+    };
     let result = unify(1, 1);
-    eval(TEST('result && unify(result.values, {})'));
+    eval(TEST('result && unify(values(result), {})'));
     result = unify(1, _);
-    eval(TEST('result && unify(result.values, {})'));
+    eval(TEST('result && unify(values(result), {})'));
     result = unify(1, v('x'));
     eval(TEST('result'));
-    eval(TEST('unify(result.values, {x: 1})'));
+    eval(TEST('unify(values(result), {x: 1})'));
     eval(TEST("v('x').isBound(result)"));
     eval(TEST("v('x').get(result) === 1"));
     result = unify(v('y'), v('x'));
     eval(TEST('result'));
-    eval(TEST('unify(result.values, {})'));
-    eval(TEST('unify(result.variables, {x: {x: 1, y: 1}, y: {x: 1, y: 1}})'));
+    eval(TEST('unify(values(result), {})'));
     eval(TEST("!v('x').isBound(result)"));
     eval(TEST("!v('y').isBound(result)"));
     eval(TEST("v('x').isAlias('y', result)"));
     eval(TEST("v('y').isAlias('x', result)"));
     eval(TEST("!v('x').isAlias('z', result)"));
     eval(TEST("!v('y').isAlias('z', result)"));
     result = unify(v('y'), _);
-    eval(TEST('result && unify(result.values, {})'));
+    eval(TEST('result && unify(values(result), {})'));
     result = unify([1, v('x')], [v('y'), 2]);
     eval(TEST('result'));
-    eval(TEST('unify(result.values, {x: 2, y: 1})'));
+    eval(TEST('unify(values(result), {x: 2, y: 1})'));
     eval(TEST("v('x').isBound(result)"));
     eval(TEST("v('x').get(result) === 2"));
     eval(TEST("v('y').isBound(result)"));
     eval(TEST("v('y').get(result) === 1"));
     result = unify({a: 1, b: v('x')}, {a: v('y'), b: 2});
     eval(TEST('result'));
-    eval(TEST('unify(result.values, {x: 2, y: 1})'));
+    eval(TEST('unify(values(result), {x: 2, y: 1})'));
     eval(TEST("v('x').isBound(result)"));
     eval(TEST("v('x').get(result) === 2"));
     eval(TEST("v('y').isBound(result)"));