mnemonica 1.0.1 → 1.0.7

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

@@ -25,7 +25,7 @@ const admin = new user.Admin({ role: 'admin' }); // inherits from user instance
 
 **Why not TypeScript interfaces alone?** TypeScript is structural at compile time: a `Payment` and an `Invoice` with identical fields are interchangeable to the type checker. At runtime, `processPayment(invoice)` silently succeeds and produces wrong results. mnemonica's runtime types are nominal — the type IS its name, established at `define()` time and stable thereafter.
 
-**Why not Object.assign / spread?** `{...raw, ...apiResult}` is one flat object with no lineage. You cannot answer "which step set `amount`?" without reading the source. mnemonica's prototype chain preserves every ancestor; `enriched.parent('ApiResult')` returns the exact API response object.
+**Why not Object.assign / spread?** `{...raw, ...apiResult}` is one flat object with no lineage. You cannot answer "which step set `amount`?" without reading the source. mnemonica's prototype chain preserves every ancestor; `utils.parent(enriched, 'ApiResult')` returns the exact API response object.
 
 ---
 
@@ -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 | undefined
 ```
 
 ---
@@ -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] | undefined;
+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] | undefined`. 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/ask/AGENTS.md

@@ -37,7 +37,7 @@ Creates type constructors with special inheritance capabilities:
 ### 3. Proxy Architecture
 
 - **TypeProxy** — Wraps type constructors, handles `.call`, `.apply`
-- **Mnemosyne** — Manages instance prototype chain, provides `.fork()`, `.parent()`
+- **Mnemosyne** — Manages instance prototype chain
 - **TypesCollectionProxy** — Manages type registry, handles type lookup
 
 ### 4. Symbol System
@@ -68,15 +68,21 @@ const TypeProxy = new Proxy(Constructor, {
 });
 ```
 
-## Explaining Instance Methods
+## Explaining Instance Introspection
 
-| Method | Purpose | Defined In |
-|--------|---------|------------|
-| `.fork()` | Create shallow copy | Mnemosyne.ts |
-| `.parent()` | Access parent instance | Mnemosyne.ts |
-| `.pick()` | Extract specific properties | Mnemosyne.ts |
-| `.extract()` | Get all inherited properties | extract.ts |
-| `.parse()` | Parse instance structure | parse.ts |
+Starting from v1.0.6 the legacy instance methods are no longer auto-injected.
+Use the standalone `utils` export:
+
+| Utility | Purpose | Defined In |
+|---------|---------|------------|
+| `utils.fork(instance)` | Create a fork constructor | fork.ts |
+| `utils.parent(instance)` | Access parent instance | parent.ts |
+| `utils.pick(instance, ...keys)` | Extract specific properties | pick.ts |
+| `utils.extract(instance)` | Get all inherited properties | extract.ts |
+| `utils.parse(instance)` | Parse instance structure | parse.ts |
+
+To restore the old `instance.fork()` / `instance.extract()` style, attach the
+methods to the constructor's prototype before calling `define()`.
 
 ## Test Framework Differences
 

package/.ai/rules-skill/contributing.md

@@ -57,7 +57,7 @@ Before implementing, I need to clarify:
 1. **Scope**: Should this config be per-type or per-collection?
 2. **Proxy compatibility**: TypeProxy handles `.get`, `.set`, `.construct`.
    Adding config requires checking all three traps.
-3. **Existing options**: `strictChain`, `blockErrors`, `exposeInstanceMethods`
+3. **Existing options**: `strictChain`, `blockErrors`, `awaitReturn`
    already exist. Does this fit the pattern?
 4. **TypeRegistry impact**: Will tactica need to regenerate types?
 

package/.ai/rules-skill/define-patterns.md

@@ -3,7 +3,7 @@ name: mnemonica-define-patterns
 description: |
   Patterns for defining types and subtypes with mnemonica's define() function.
   Use when the user asks about define(), creating types, subtype inheritance,
-  strictChain, blockErrors, exposeInstanceMethods, or type configuration options.
+  strictChain, blockErrors, awaitReturn, or type configuration options.
 metadata:
   tags: [mnemonica, define, types, subtypes, inheritance]
 ---
@@ -71,9 +71,15 @@ define('Parent.Child', function (this: Child, data: Data) {
 | `blockErrors` | `true` | Block construction if error exists in prototype chain |
 | `submitStack` | `false` | Collect stack trace as `__stack__` property |
 | `awaitReturn` | `true` | `await new Constructor()` must return a value |
-| `exposeInstanceMethods` | `true` | Expose `extract()`, `fork()`, etc. on instance |
 | `asClass` | auto-detected | Force class mode detection |
 
+## Instance Method Opt-In
+
+Starting from v1.0.6, `extract()`, `pick()`, `parent()`, `fork()`, `exception()`,
+`sibling()`, and `clone()` are **not** auto-injected on instances. Use the standalone
+`utils` export, or attach the methods to the constructor's prototype before calling
+`define()`.
+
 ## Before/After: strictChain
 
 **Before** (strictChain: false — allows broken chains)

package/.ai/rules-skill/ecosystem.md

@@ -56,7 +56,7 @@ supports different users.
 
 | Environment | Tools |
 |-------------|-------|
-| **VS Code** | Mnemographica extension, Tactica LSP, Mnemonica Logger |
+| **VS Code** | Mnemographica extension, Tactica CLI, Mnemonica Logger |
 | **Runtime (Node.js)** | CDP Connection (port 9229), Strategy MCP (ports 9230/9231) |
 
 #### Collaboration Modes
@@ -76,7 +76,7 @@ supports different users.
 │         Mnemonica Ecosystem             │
 ├─────────────────────────────────────────┤
 │  mnemographica  │  VS Code Extension    │
-│  tactica        │  Type Generator/LSP   │
+│  tactica        │  Type Generator/CLI   │
 │  strategy       │  MCP Server           │
 │  topologica     │  Module Loader        │
 │  mnemonica      │  Core Runtime         │
@@ -88,7 +88,7 @@ supports different users.
 
 ### Integration Points
 
-1. **Tactica → VS Code**: Language Service Plugin
+1. **Tactica → VS Code**: CLI type generator
 2. **Strategy → CDP**: Runtime evaluation
 3. **Mnemographica → Strategy**: HTTP/WebSocket servers
 4. **All → Topologica**: Module loading
@@ -136,5 +136,5 @@ interface Runnable { run(): void; }
 
 ## References
 
-- [Wikipedia: PACT (interaction design)](https://en.wikipedia.org/wiki/PACT_\(interaction_design\))
+- [Wikipedia: PACT (interaction design)](https://en.wikipedia.org/wiki/PACT_%28interaction_design%29)
 - `strategy/README.md` — MCP architecture