mnemonica 1.0.6 → 1.0.8

package/.ai/AGENTS.md

@@ -132,7 +132,7 @@ Based on observed agent behavior:
 | [`rules-skill/philosophy.md`](./rules-skill/philosophy.md) | HoTT concepts applied to mnemonica's self-reflection model |
 | [`rules-skill/ecosystem.md`](./rules-skill/ecosystem.md) | PACT framework: personas, collaboration modes, integration points |
 | [`rules-skill/contributing.md`](./rules-skill/contributing.md) | Behavioral guidelines for AI contributors |
-| [`TACTICA-DEEP-DIVE.md`](./TACTICA-DEEP-DIVE.md) | Comprehensive tactica + lookupTyped technical guide |
+| [`TACTICA-DEEP-DIVE.md`](./TACTICA-DEEP-DIVE.md) | Comprehensive tactica + lookup technical guide |
 | [`../docs/async-constructors.md`](../docs/async-constructors.md) | Async constructors: super() return values, native class mixing, chains |
 
 - Main README: [`../README.md`](../README.md)

package/.ai/ONBOARDING.md

@@ -103,7 +103,7 @@ src/
 Key components:
 - **TypeProxy** — wraps type constructors
 - **InstanceCreator** — orchestrates construction lifecycle
-- **Mnemosyne** — handles instance method access via Proxy
+- **Mnemosyne** — root memory proxy; stores construction context and resolves subtype lookups
 
 ---
 
@@ -159,6 +159,7 @@ Read [`../docs/async-constructors.md`](../docs/async-constructors.md) for the `s
 |------|------|
 | Coding standards, type rules | [`CODE.md`](./CODE.md) |
 | Design patterns, constraints | [`ARCHITECT.md`](./ARCHITECT.md) |
+| Prototype chain internals | [`PROTOTYPE-CHAIN.md`](./PROTOTYPE-CHAIN.md) |
 | Debugging commands, issues | [`DEBUG.md`](./DEBUG.md) |
 | Async constructor deep dive | [`../docs/async-constructors.md`](../docs/async-constructors.md) |
 | tactica type-safe lookup | [`TACTICA-RULES.md`](./TACTICA-RULES.md) |

package/.ai/PROTOTYPE-CHAIN.md

@@ -0,0 +1,122 @@
+# Prototype Chain Architecture
+
+## Why this document exists
+
+mnemonica instances do not have a normal JavaScript prototype chain. Between every parent instance and child instance there are two intermediate objects. If you are changing construction, props storage, `instanceof`, or subtype lookup, you need to know what those objects are and why they exist.
+
+## High-level shape
+
+For a chain `user → admin → superadmin` the instance-level chain is:
+
+```
+superadmin
+  └── SuperAdminType.prototype
+        └── SuperAdminMemory
+              └── admin
+                    └── AdminType.prototype
+                          └── AdminMemory
+                                └── user
+                                      └── UserType.prototype
+                                            └── UserMemory
+                                                  └── root Mnemosyne Proxy
+                                                        └── Mnemonica instance
+                                                              └── Mnemonica.prototype
+                                                                    └── uranus
+```
+
+`SuperAdminMemory`, `AdminMemory`, and `UserMemory` are the **memory layers**. Only `UserMemory`’s parent is the real `Mnemosyne` constructor result wrapped in a Proxy. The deeper memory layers are plain objects that play the same role.
+
+## The three levels contributed by each type
+
+Every mnemonica type adds three levels to the chain:
+
+1. **Instance object** — the object returned by `new parent.ChildType(...)`. Holds only the own properties assigned by the user constructor.
+2. **`ModificatorType.prototype`** — the user-prototype layer. Holds methods and getters captured at `define()` time. It gets a fresh `constructor` property pointing to the per-construction `ModificatorType` function.
+3. **Memory layer** — a plain object whose `[[Prototype]]` is the parent instance. It is the `WeakMap` key for internal props and has a `constructor` getter returning `ModificatorType`.
+
+## Files and functions involved
+
+- `src/api/types/compileNewModificatorFunctionBody.ts` builds the `ModificatorType`, the actual function or class used for `new`. For function constructors it preserves `new.target`; for class constructors it generates a class that extends the user class so `super(...)` works.
+- `src/api/types/createInstanceModificator.ts` is the default `ModificationConstructor`. It creates the memory layer, wires `_addProps`, copies the captured user prototype onto `ModificatorType.prototype`, and rewires `ModificatorType.prototype` to inherit from the memory layer.
+- `src/api/types/Props.ts` implements `_addProps` and `getProps`. Internal props are stored in a module-level `WeakMap` keyed by the memory-layer object.
+- `src/api/types/Mnemosyne.ts` builds the root memory proxy. Only the root type goes through `createMnemosyne`; all deeper memory layers are plain objects produced by `createInstanceModificator`.
+- `src/api/types/InstanceCreator.ts` orchestrates the pipeline and passes `existentInstance` (the parent instance) into the `ModificationConstructor`.
+- `src/api/types/TypeProxy.ts` is the constructor-like object returned by `define()`. Its `construct` trap creates the root Mnemosyne proxy and then invokes `InstanceCreator`.
+
+## Capturing the user prototype
+
+At `define()` time the `TypeDescriptor` stores `proto` — a snapshot of the user constructor’s `.prototype`. During construction that snapshot is copied onto the fresh `ModificatorType.prototype`. The user constructor’s original `.prototype` is restored after construction, so it is never part of the instance chain.
+
+This is why the same constructor function can be reused across multiple type definitions without bleeding prototype state.
+
+## Internal props storage
+
+`_addProps` receives the memory-layer object and stores a `value` object in the module `WeakMap` keyed by that object. The stored object contains getters for:
+
+- `__type__`
+- `__parent__`
+- `__args__`
+- `__timestamp__`
+- `__creator__`
+- `__collection__`
+- `__subtypes__`
+- `__proto_proto__`
+- `__stack__`
+
+`getProps(instance)` walks the prototype chain from the instance until it finds the first object with a `WeakMap` entry. That is always the instance’s own memory layer. `parent(instance)` reads `__parent__` from that props object; it is the `existentInstance` passed to `InstanceCreator`.
+
+## `_setSelf` and async construction
+
+`_setSelf(instance)` is called at the end of successful construction. It adds one more getter to the props object:
+
+```js
+__self__: () => instance
+```
+
+Then it stores the props object in the `WeakMap` keyed by the instance itself. This solves the async-constructor problem.
+
+When a constructor returns a Promise, the initial value of `new Constructor()` is that Promise. `makeAwaiter` waits for resolution, then checks:
+
+```js
+if (props.__self__ !== self.inheritedInstance) {
+  self.postProcessing(type);
+}
+```
+
+If `__self__` is missing or does not match the resolved instance, post-processing has not run yet, so it runs validation and hooks. If it matches, post-processing has already happened and is skipped. The constructor can therefore return a Promise, and mnemonica finalizes the instance only after the Promise resolves — without double-initializing or losing the construction context.
+
+## Subtype lookup
+
+Only the root has a Proxy. When you access `admin.SomeSubType`, the property lookup walks:
+
+```
+admin → AdminType.prototype → AdminMemory → user → UserType.prototype → UserMemory → root Mnemosyne Proxy
+```
+
+The Proxy’s `get` trap calls `prepareSubtypeForConstruction(prop, receiver)`. It uses `_getProps` to find the memory layer of `receiver` by walking from `Reflect.getPrototypeOf(receiver)`, reads `__subtypes__`, and returns a `SubTypeProxy` that closes over the subtype `TypeDef` and the parent instance.
+
+This means the root Proxy serves the entire branch below it.
+
+## Why the root Proxy is kept
+
+The root Proxy exists so that **subtypes defined after an instance is created are still visible on that instance**.
+
+If subtype constructors were attached to the memory layer at construction time, an instance would only know about the subtypes that existed when it was built. Any `ParentType.define('NewSubType', ...)` call afterward would not appear on existing instances.
+
+The Proxy avoids that by doing a live lookup in the type’s `__subtypes__` Map on every property access. Instances do not carry a snapshot of the Trie; they delegate to the current type graph. That decouples instance lifetime from type-graph evolution and is the main reason a Proxy is necessary. The other Proxy-based mechanisms in the codebase could be replaced with simpler constructs, but this live lookup is hard to achieve without a Proxy.
+
+## Classes vs functions
+
+The final chain shape is identical for class and function definitions. The difference is only in how `ModificatorType` runs the user constructor:
+
+- **Function:** the wrapper temporarily swaps `ConstructHandler.prototype`, calls `new ConstructHandler(...)`, then restores it.
+- **Class:** the generated class `extends ConstructHandler`, calls `super(...)`, then runs the post-construction handler.
+
+In both cases the resulting prototype chain is rewired to `instance → ModificatorType.prototype → memoryLayer → parent`.
+
+## Common mistakes
+
+- **Assuming internal props are own properties of the instance.** They are stored in a `WeakMap` keyed by the memory layer.
+- **Assuming `instance.constructor` is the user’s original function.** It points to the per-construction `ModificatorType`, which delegates behavior to the user handler.
+- **Thinking the `Mnemosyne` constructor is used for every instance.** It is used once for the root; subtype memory layers are plain objects.
+- **Expecting the user constructor’s `.prototype` to be in the chain.** It is snapshotted and restored; only copies of its descriptors end up on `ModificatorType.prototype`.

package/.ai/TACTICA-DEEP-DIVE.md

@@ -12,7 +12,7 @@
 3. [How tactica Bridges the Gap](#3-how-tactica-bridges-the-gap)
 4. [Declaration Merging: The TypeScript Mechanism](#4-declaration-merging-the-typescript-mechanism)
 5. [tsconfig.json Setup](#5-tsconfigjson-setup)
-6. [How lookupTyped Works](#6-how-lookuptyped-works)
+6. [How lookup Works](#6-how-lookuptyped-works)
 7. [Why Direct Import Fails](#7-why-direct-import-fails)
 8. [The Epiphany: Zero-Cast Chaining](#8-the-epiphany-zero-cast-chaining)
 9. [Common Mistakes](#9-common-mistakes)
@@ -188,12 +188,12 @@ declare module 'some-lib' {
 
 ### 4.3 How tactica Uses It
 
-mnemonica core defines:
+mnemonica core defines an empty `TypeRegistry`:
 
 ```typescript
-// In mnemonica core (src/types/index.ts)
+// In mnemonica core (src/index.ts)
 export interface TypeRegistry {
-	[key: string]: never;  // Empty by default, prevents accidental usage
+	// Intentionally empty. Augment via declaration merging.
 }
 ```
 
@@ -203,37 +203,33 @@ tactica generates:
 // In .tactica/registry.ts
 declare module 'mnemonica' {
 	interface TypeRegistry {
-		'RequestData': new (...args: unknown[]) => RequestData;
+		'RequestData': TypeConstructor<RequestData>;
 	}
 }
 ```
 
 After this augmentation, `TypeRegistry` contains the `'RequestData'` key. Any code that imports from `'mnemonica'` sees the augmented `TypeRegistry`.
 
-### 4.4 Why `[key: string]: never`?
+### 4.4 Why an Empty `TypeRegistry`?
 
-The `[key: string]: never` pattern in the base `TypeRegistry` is a TypeScript trick:
+The base `TypeRegistry` is intentionally empty:
 
 ```typescript
-interface TypeRegistry {
-	[key: string]: never;
-}
-
-type Test = TypeRegistry['anything']; // Error: Type 'anything' is not assignable to type 'never'
+export interface TypeRegistry {}
 ```
 
-This means **you cannot use `TypeRegistry` without augmentation**. It forces you to run tactica and generate the registry. Without it, any `lookupTyped('Something')` would be a compile error.
+Without augmentation, `lookup('Something')` falls back to the broad `TypeClass | undefined` return type. This keeps the library usable without a registry while still allowing full type inference once you augment it.
 
 Once augmented:
 
 ```typescript
 declare module 'mnemonica' {
 	interface TypeRegistry {
-		'RequestData': new (...args: unknown[]) => RequestData;
+		'RequestData': TypeConstructor<RequestData>;
 	}
 }
 
-type Test = TypeRegistry['RequestData']; // OK — returns the constructor type
+const RequestData = lookup('RequestData'); // typed constructor
 ```
 
 ---
@@ -272,30 +268,37 @@ For declaration merging to work, the `.tactica/registry.ts` file must be include
 TypeScript only processes files in the `include` array. If `.tactica/` is not included:
 
 ```typescript
-import { lookupTyped } from 'mnemonica';
-const RequestData = lookupTyped('RequestData');
-// Error: 'RequestData' is not assignable to parameter of type 'never'
+import { lookup } from 'mnemonica';
+const RequestData = lookup('RequestData');
+// RequestData is typed as TypeClass | undefined instead of the concrete constructor
 ```
 
-Because without the augmentation, `TypeRegistry` still has `[key: string]: never`.
+Because without the augmentation, `TypeRegistry` is empty and `lookup()` falls back to its unaugmented overload.
 
 ---
 
-## 6. How lookupTyped Works
+## 6. How lookup Works
 
 ### 6.1 Runtime Behavior
 
 ```typescript
 // In mnemonica core (src/index.ts)
-export const lookupTyped = function <const K extends keyof TypeRegistry>(
+export function lookup<const K extends keyof TypeRegistry>(
+	this: unknown,
 	TypeNestedPath: K
-): TypeRegistry[K] {
-	// Runtime delegates to lookup()
-	return types.lookup(TypeNestedPath as string) as TypeRegistry[K];
+): TypeRegistry[K];
+export function lookup(
+	this: unknown,
+	TypeNestedPath: string
+): TypeClass | undefined {
+	// Runtime delegates to types.lookup()
+	const types = checkThis(this) ? defaultTypes : this || defaultTypes;
+	return types.lookup(TypeNestedPath);
+}
 };
 ```
 
-At runtime, `lookupTyped('RequestData')`:
+At runtime, `lookup('RequestData')`:
 1. Calls `types.lookup('RequestData')`
 2. Searches the default types collection
 3. Returns the constructor function
@@ -307,7 +310,7 @@ At runtime, `lookupTyped('RequestData')`:
 At compile time, TypeScript sees:
 
 ```typescript
-const RequestData = lookupTyped('RequestData');
+const RequestData = lookup('RequestData');
 ```
 
 TypeScript infers:
@@ -350,7 +353,7 @@ It checks the constructor signature → `new (...args: unknown[]) => RequestData
 
 ## 7. Why Direct Import Fails
 
-Let's trace what happens with direct import vs `lookupTyped`.
+Let's trace what happens with direct import vs `lookup`.
 
 ### 7.1 Direct Import
 
@@ -370,12 +373,12 @@ const routeData = new requestData.RouteData({ ... });
 
 The direct import returns the constructor, but TypeScript's type for that constructor doesn't include `.RouteData`. The `define()` function's return type is not augmented with sub-constructor information.
 
-### 7.2 lookupTyped
+### 7.2 lookup
 
 ```typescript
-import { lookupTyped } from 'mnemonica';
+import { lookup } from 'mnemonica';
 
-const RequestData = lookupTyped('RequestData');
+const RequestData = lookup('RequestData');
 //          ↑
 //          TypeScript sees: TypeRegistry['RequestData']
 //          Which is: new (...args: unknown[]) => RequestData
@@ -431,9 +434,9 @@ Creates:
 
 ```typescript
 // src/server.ts or any file
-import { lookupTyped } from 'mnemonica';
+import { lookup } from 'mnemonica';
 
-const RequestData = lookupTyped('RequestData');
+const RequestData = lookup('RequestData');
 ```
 
 ### Step 4: Chain (Zero Casts)
@@ -463,7 +466,7 @@ const requestData = new RequestData({ ... }) as unknown as RequestDataT;
 
 **Why wrong:** You are fighting the type system instead of using it. Every cast is a bug waiting to happen. If the type changes, the cast still compiles but may break at runtime.
 
-**Fix:** Use `lookupTyped`.
+**Fix:** Use `lookup`.
 
 ### 9.2 "I'll import the generated types too"
 
@@ -476,23 +479,23 @@ const requestData = new RequestData({ ... }) as unknown as RequestDataT;
 
 **Why wrong:** You are importing both the runtime constructor AND the generated type, then bridging them with a cast. This is twice the work and still unsafe.
 
-**Fix:** Use `lookupTyped` — it gives you both the runtime constructor AND the type in one call.
+**Fix:** Use `lookup` — it gives you both the runtime constructor AND the type in one call.
 
-### 9.3 "lookupTyped only works in route handlers"
+### 9.3 "lookup only works in route handlers"
 
 ```typescript
 // ❌ WRONG (unnecessary)
 app.get('/test', async () => {
-	const RequestData = lookupTyped('RequestData');
+	const RequestData = lookup('RequestData');
 	const requestData = new RequestData({ ... });
 });
 ```
 
-**Why wrong:** `lookupTyped` is a runtime lookup, but it's deterministic and cached. Calling it at module level is perfectly fine and more efficient:
+**Why wrong:** `lookup` is a runtime lookup, but it's deterministic and cached. Calling it at module level is perfectly fine and more efficient:
 
 ```typescript
 // ✅ CORRECT
-const RequestData = lookupTyped('RequestData');
+const RequestData = lookup('RequestData');
 
 app.get('/test', async () => {
 	const requestData = new RequestData({ ... });
@@ -504,19 +507,19 @@ app.get('/test', async () => {
 ```typescript
 // ❌ WRONG (mixing patterns)
 import { RequestData } from './collections/requestTypes.js';
-const TypedRequestData = lookupTyped('RequestData');
+const TypedRequestData = lookup('RequestData');
 
 app.decorate('RequestData', RequestData);  // direct import
-const requestData = new TypedRequestData({ ... });  // lookupTyped
+const requestData = new TypedRequestData({ ... });  // lookup
 ```
 
 **Why wrong:** You're maintaining two references to the same object.
 
-**Fix:** Use `lookupTyped` for everything. The returned constructor is the same object:
+**Fix:** Use `lookup` for everything. The returned constructor is the same object:
 
 ```typescript
 // ✅ CORRECT
-const RequestData = lookupTyped('RequestData');
+const RequestData = lookup('RequestData');
 
 app.decorate('RequestData', RequestData);
 const requestData = new RequestData({ ... });
@@ -527,7 +530,7 @@ const requestData = new RequestData({ ... });
 ```typescript
 // You add a new property to the define() call
 // But forget to run tactica
-const RequestData = lookupTyped('RequestData');
+const RequestData = lookup('RequestData');
 const requestData = new RequestData({ newField: 'value' });
 // Error: Object literal may only specify known properties
 ```
@@ -544,10 +547,10 @@ npm run tactica
 
 | I want to... | Do this | Don't do this |
 |---|---|---|
-| Get a typed constructor | `const T = lookupTyped('T')` | `import { T } from './collections/T.js'` |
+| Get a typed constructor | `const T = lookup('T')` | `import { T } from './collections/T.js'` |
 | Create an instance | `new T({ ... })` | `new T({ ... }) as unknown as TT` |
 | Chain to a child type | `new instance.Child({ ... })` | `new (instance as any).Child({ ... })` |
-| Decorate Fastify | `app.decorate('T', T)` with `lookupTyped` | Direct import + separate lookupTyped |
+| Decorate Fastify | `app.decorate('T', T)` with `lookup` | Direct import + separate lookup |
 | Add a new property | Modify `define()` → run `tactica` | Modify `define()` + manual cast |
 | Fix "Property does not exist" | Run `tactica` to regenerate | Add `as any` or `as unknown` |
 
@@ -575,9 +578,9 @@ This pattern works because:
 
 1. **mnemonica creates a Trie at runtime** — sub-constructors exist, instances can spawn children
 2. **tactica teaches TypeScript about the Trie** — via declaration merging of `TypeRegistry`
-3. **lookupTyped retrieves the typed constructor** — compile-time type safety + runtime correctness
-4. **The same object is returned either way** — `import { T }` and `lookupTyped('T')` are identical at runtime
+3. **lookup retrieves the typed constructor** — compile-time type safety + runtime correctness
+4. **The same object is returned either way** — `import { T }` and `lookup('T')` are identical at runtime
 
-**The only difference is TypeScript's knowledge.** Use `lookupTyped` and let TypeScript help you.
+**The only difference is TypeScript's knowledge.** Use `lookup` and let TypeScript help you.
 
-If you find yourself writing `as unknown as` with mnemonica types, **you have taken a wrong turn.** Stop. Use `lookupTyped`. Trust the registry.
+If you find yourself writing `as unknown as` with mnemonica types, **you have taken a wrong turn.** Stop. Use `lookup`. Trust the registry.

package/.ai/TACTICA-RULES.md

@@ -1,6 +1,6 @@
-# mnemonica + `lookupTyped`: rules and the underlying pattern
+# mnemonica + `lookup`: rules and the underlying pattern
 
-> **The real rule:** use `lookupTyped()` plus an augmented `TypeRegistry` — never `import { X } from './collections/...'` plus `as unknown as` casts. The augmentation can be hand-written or generated by [`@mnemonica/tactica`](https://www.npmjs.com/package/@mnemonica/tactica). Tactica is the productivity tool; the **augmentation** is the requirement. For the full mechanism and a side-by-side example, see [`../docs/typed-lookup.md`](../docs/typed-lookup.md).
+> **The real rule:** use `lookup()` plus an augmented `TypeRegistry` — never `import { X } from './collections/...'` plus `as unknown as` casts. The augmentation can be hand-written or generated by [`@mnemonica/tactica`](https://www.npmjs.com/package/@mnemonica/tactica). Tactica is the productivity tool; the **augmentation** is the requirement. For the full mechanism and a side-by-side example, see [`../docs/typed-lookup.md`](../docs/typed-lookup.md).
 
 ---
 
@@ -33,13 +33,13 @@ The temptation is to cast around the gap:
 const requestData = new RequestData({ ... }) as unknown as RequestDataT;
 ```
 
-That bypasses the type system. The right answer is to teach TypeScript what the Trie looks like — which is exactly what `lookupTyped()` + a `TypeRegistry` augmentation does.
+That bypasses the type system. The right answer is to teach TypeScript what the Trie looks like — which is exactly what `lookup()` + a `TypeRegistry` augmentation does.
 
 ---
 
 ## The mechanism in one paragraph
 
-`mnemonica` exports `interface TypeRegistry { [key: string]: TypeConstructor<never> }`. `lookupTyped<K extends keyof TypeRegistry>(path: K)` returns `TypeRegistry[K]`. So a `declare module 'mnemonica' { interface TypeRegistry { ... } }` augmentation in your project — by hand, or generated by tactica — gives `lookupTyped('Path.To.Type')` a fully typed return value. Zero casts.
+`mnemonica` exports an empty `interface TypeRegistry {}`. `lookup<const K extends keyof TypeRegistry>(path: K)` returns `TypeRegistry[K]`. So a `declare module 'mnemonica' { interface TypeRegistry { ... } }` augmentation in your project — by hand, or generated by tactica — gives `lookup('Path.To.Type')` a fully typed return value. Zero casts.
 
 After augmentation, TypeScript knows:
 - The constructor arguments for each type
@@ -62,7 +62,7 @@ When asked to work with a mnemonica project:
 
 2. **If `.tactica/` exists, check `tsconfig.json` includes it.** If missing, add `.tactica/**/*.ts` to `include`.
 
-3. **Check that `lookupTyped` is being used.** Direct imports from collection files + casts are the smell that augmentation is missing or unused.
+3. **Check that `lookup` is being used.** Direct imports from collection files + casts are the smell that augmentation is missing or unused.
 
 4. **Never accept `as unknown as` as a solution.** It is a symptom of the augmentation being missing, not a fix.
 
@@ -72,7 +72,7 @@ When asked to work with a mnemonica project:
 
 | Situation | Wrong | Right |
 |---|---|---|
-| Get a constructor | `import { T } from './collections/T.js'` | `const T = lookupTyped('T')` |
+| Get a constructor | `import { T } from './collections/T.js'` | `const T = lookup('T')` |
 | Create instance | `new T({ ... }) as unknown as TT` | `new T({ ... })` |
 | Chain to child | `new (instance as any).Child({ ... })` | `new instance.Child({ ... })` |
 | Type not found | Add `as any` | Augment `TypeRegistry` (manually or run `tactica`) |
@@ -96,8 +96,8 @@ If you are not using tactica, `npm run tactica` is not required; the hand-writte
 
 ## Deeper reading
 
-- [`../docs/typed-lookup.md`](../docs/typed-lookup.md) — `lookupTyped` with or without tactica (canonical reference, side-by-side)
+- [`../docs/typed-lookup.md`](../docs/typed-lookup.md) — `lookup` with or without tactica (canonical reference, side-by-side)
 - [`../docs/tactica-pattern.md`](../docs/tactica-pattern.md) — human-facing explanation of declaration merging
 - [`./TACTICA-DEEP-DIVE.md`](./TACTICA-DEEP-DIVE.md) — comprehensive technical guide
 
-The key insight: **the runtime constructor is identical whether you import it directly or look it up. The only difference is TypeScript's compile-time knowledge.** `lookupTyped` + augmented `TypeRegistry` teaches TypeScript what mnemonica already knows at runtime — and the augmentation can come from anywhere.
+The key insight: **the runtime constructor is identical whether you import it directly or look it up. The only difference is TypeScript's compile-time knowledge.** `lookup` + augmented `TypeRegistry` teaches TypeScript what mnemonica already knows at runtime — and the augmentation can come from anywhere.

package/.ai/rules-skill/lookup-typed.md

@@ -1,47 +1,45 @@
 ---
 name: mnemonica-lookup-typed
 description: |
-  Type-safe lookup with lookupTyped() and TypeRegistry augmentation.
-  Use when the user asks about lookupTyped, TypeRegistry, tactica-generated types,
+  Type-safe lookup with lookup() and TypeRegistry augmentation.
+  Use when the user asks about lookup, TypeRegistry, tactica-generated types,
   declaration merging, or type-safe constructor retrieval in mnemonica.
 metadata:
   tags: [mnemonica, lookup, types, tactica, declaration-merging]
 ---
 
-# Type-Safe Lookup with lookupTyped()
+# Type-Safe Lookup with `lookup()`
 
-## lookup() vs lookupTyped()
+## `lookup()` with and without `TypeRegistry` augmentation
 
 ```typescript
-import { lookup, lookupTyped } from 'mnemonica';
+import { lookup } from 'mnemonica';
 
-// Runtime only, returns unknown type
+// Without augmentation: returns TypeClass | undefined
 const SomeType = lookup('SomeType');
 const instance = new SomeType({ ... }); // no type safety
 
-// Compile-time type safety via TypeRegistry augmentation
-const SomeType = lookupTyped('SomeType');
+// With augmentation: returns the typed constructor
+const SomeType = lookup('SomeType');
 const instance = new SomeType({ ... }); // TypeScript knows the signature
 ```
 
 ## TypeRegistry Pattern
 
-The default `TypeRegistry` uses `[key: string]: TypeConstructor<never>` to
-enforce augmentation via declaration merging. Without augmentation, any key
-lookup produces a compile-time error because `TypeConstructor<never>` is not
-assignable to concrete types.
+The default `TypeRegistry` is an empty interface. Application code or
+`@mnemonica/tactica` augments it through TypeScript declaration merging.
 
 ```typescript
 // In mnemonica core
 export interface TypeRegistry {
-	[key: string]: TypeConstructor<never>;
+	// Intentionally empty. Augment via declaration merging.
 }
 
 // Generated by tactica in .tactica/registry.ts
 declare module 'mnemonica' {
 	interface TypeRegistry {
-		'UserType': new (...args: unknown[]) => UserTypeInstance;
-		'Parent.SubType': new (...args: unknown[]) => SubTypeInstance;
+		'UserType': TypeConstructor<UserTypeInstance>;
+		'Parent.SubType': TypeConstructor<SubTypeInstance>;
 	}
 }
 ```
@@ -52,9 +50,9 @@ The axis that actually matters is whether `TypeRegistry` has been augmented for
 
 | Feature | Unaugmented `TypeRegistry` | Augmented `TypeRegistry` |
 |---------|---------------------------|--------------------------|
-| Constructor retrieval | `lookup('Name')` returns `unknown` | `lookupTyped('Name')` returns typed constructor |
+| Constructor retrieval | `lookup('Name')` returns `TypeClass \| undefined` | `lookup('Name')` returns typed constructor |
 | Type safety | Runtime only | Compile-time + runtime |
-| Registry default | `[key: string]: TypeConstructor<never>` | Per-key constructor signatures |
+| Registry default | Empty interface | Per-key constructor signatures |
 | Instance properties | `any` / `unknown` | Fully typed |
 
 Two ways to augment: hand-written `.d.ts` (small projects, learning) or [`@mnemonica/tactica`](https://www.npmjs.com/package/@mnemonica/tactica) (auto-generated, recommended for non-trivial projects). See [`../../docs/typed-lookup.md`](../../docs/typed-lookup.md) for both paths side by side.
@@ -65,7 +63,7 @@ Two ways to augment: hand-written `.d.ts` (small projects, learning) or [`@mnemo
 ```typescript
 const UserType = lookup('UserType');
 const user = new UserType({ name: 'John' });
-// user is typed as unknown — no IntelliSense for properties
+// user is typed as object — no IntelliSense for properties
 ```
 
 **After** (TypeRegistry augmented — either hand-written or tactica-generated; runtime is identical)
@@ -78,7 +76,7 @@ declare module 'mnemonica' {
 }
 
 // In application code
-const UserType = lookupTyped('UserType');
+const UserType = lookup('UserType');
 const user = new UserType({ name: 'John' });
 // user is fully typed as UserTypeInstance
 ```

package/AGENTS.md

@@ -53,7 +53,7 @@ Load the docs that match your change type. The wrong context produces broken cod
 | Involves async constructors | + [`.ai/rules-skill/async-constructors.md`](./.ai/rules-skill/async-constructors.md) + [`.ai/async_init.md`](./.ai/async_init.md) |
 | Involves TypeScript types | + [`.ai/rules-skill/type-system.md`](./.ai/rules-skill/type-system.md) |
 | Involves proxy internals | + [`.ai/rules-skill/proxy-architecture.md`](./.ai/rules-skill/proxy-architecture.md) |
-| Uses tactica / `lookupTyped` | + [`.ai/TACTICA-RULES.md`](./.ai/TACTICA-RULES.md) |
+| Uses tactica / `lookup` | + [`.ai/TACTICA-RULES.md`](./.ai/TACTICA-RULES.md) |
 | Docs-only change | README section you're touching only |
 
 **This file + `.ai/ONBOARDING.md` are the always-required baseline for any `src/` edit.**
@@ -92,22 +92,28 @@ The core API is `define(TypeName, constructHandler, config?)` in `src/index.ts`.
 - `.lookup()` - find types by path
 - `.registerHook()` - register lifecycle hooks
 
-### The `lookupTyped()` Function
+### The `lookup()` Function
 
-For user-facing semantics, see [`README.md`](./README.md) and [`.ai/TACTICA-RULES.md`](./.ai/TACTICA-RULES.md). The contributor-relevant detail is the implementation pattern: `TypeRegistry` exposes a `[key: string]: never` index so that any lookup against an unaugmented registry is a compile-time error.
+For user-facing semantics, see [`README.md`](./README.md) and [`.ai/TACTICA-RULES.md`](./.ai/TACTICA-RULES.md). The contributor-relevant detail is the implementation pattern: `TypeRegistry` starts empty, and `lookup()` uses overloads so augmented keys return the typed constructor while unaugmented keys fall back to `TypeClass | undefined`.
 
 ```typescript
 // In mnemonica core (src/index.ts)
 export interface TypeRegistry {
-	[key: string]: never;  // forces augmentation before keys resolve to real types
+	// Intentionally empty. Augment via declaration merging.
 }
 
-export const lookupTyped = function <const K extends keyof TypeRegistry>(
+export function lookup<const K extends keyof TypeRegistry>(
+	this: unknown,
 	TypeNestedPath: K
-): TypeRegistry[K] {
-	// Runtime delegates to lookup(); type safety is compile-time only.
-	return types.lookup(TypeNestedPath as string) as TypeRegistry[K];
-};
+): TypeRegistry[K];
+export function lookup(
+	this: unknown,
+	TypeNestedPath: string
+): TypeClass | undefined {
+	// Runtime delegates to types.lookup(); type safety is compile-time only.
+	const types = checkThis(this) ? defaultTypes : this || defaultTypes;
+	return types.lookup(TypeNestedPath);
+}
 ```
 
 Tactica generates the augmentation:
@@ -116,15 +122,15 @@ Tactica generates the augmentation:
 // In .tactica/registry.ts (generated)
 declare module 'mnemonica' {
 	interface TypeRegistry {
-		'UserType': new (...args: unknown[]) => UserTypeInstance;
-		'Parent.SubType': new (...args: unknown[]) => SubTypeInstance;
+		'UserType': TypeConstructor<UserTypeInstance>;
+		'Parent.SubType': TypeConstructor<SubTypeInstance>;
 	}
 }
 ```
 
-Runtime behavior is identical to `lookup()`; the only difference is the compile-time constraint on the key.
+Runtime behavior is identical whether `TypeRegistry` is augmented or not; the only difference is the compile-time return type.
 
-> **Roadmap.** Nested `lookupTyped()` (a type-safe `.lookupTyped()` method
+> **Roadmap.** Nested `lookup()` (a type-safe `.lookup()` method
 > on constructors that preserves the prototype chain) is designed but not
 > yet shipped.
 

package/CONTRIBUTING.md

@@ -51,7 +51,7 @@ behavior that the type system tolerates, and vice versa.
 Conventional commits are preferred:
 
 ```
-feat: add lookupTyped overload for nested registry
+feat: add lookup overload for nested registry
 fix(InstanceCreator): preserve __args__ across async chain
 docs: clarify instance method opt-in pattern
 chore(ci): bump setup-node to v4