mnemonica 1.0.1 → 1.0.7

package/.ai/rules-skill/instance-methods.md

@@ -2,33 +2,66 @@
 name: mnemonica-instance-methods
 description: |
   Instance methods and properties in mnemonica: extract, pick, parent, fork,
-  clone, getProps, and the internal __self__ reference. Use when the user asks
-  about instance introspection, prototype chain traversal, forking instances,
-  or the internal props system.
+  clone, sibling, exception, getProps, and the internal __self__ reference.
+  Starting from v1.0.6 these convenience methods are no longer auto-injected;
+  use the standalone utils.* API or attach them to a constructor prototype before
+  calling define().
 metadata:
   tags: [mnemonica, instances, methods, introspection, prototype]
 ---
 
 # Instance Methods
 
-## Available Methods
+For the type-level details of the corresponding standalone utilities
+(`utils.extract`, `utils.pick`, `utils.parent`, `utils.fork`, `utils.clone`,
+`utils.sibling`, `utils.exception`), see [`docs/UTILS.md`](../../docs/UTILS.md).
 
-| Method | Description |
-|--------|-------------|
-| `extract()` | Returns all enumerable properties as a plain object |
-| `pick(...keys)` | Returns selected properties |
-| `parent()` | Returns the parent instance in the prototype chain |
-| `parent(path)` | Looks up parent by constructor name |
-| `fork(...args)` | Creates a new instance with same or different args |
-| `clone` | Alias for `fork()` with no arguments |
-| `exception(error, ...args)` | Creates an error with context |
-| `sibling(name)` | Finds a sibling type by name |
+## Standalone Utilities (Default)
+
+Starting from v1.0.6 the convenience methods are **not** exposed on instances by
+default. Import them from the `utils` export:
+
+```typescript
+import { utils } from 'mnemonica';
+
+utils.extract(instance);
+utils.pick(instance, 'name', 'age');
+utils.parent(instance, 'UserType');
+utils.fork(instance)(newArgs);
+utils.clone(instance);
+utils.sibling(instance);
+utils.exception(instance, new Error('oops'));
+```
+
+All utilities infer their type parameter from the instance argument.
+
+## Legacy Instance-Method Style (Opt-In)
+
+To restore the old `instance.extract()` style for a root constructor, attach the
+methods to its prototype **before** passing it to `define()`. See
+`test/instance-methods-helper.js` for the full reference pattern.
+
+```typescript
+import { define, utils } from 'mnemonica';
+
+function UserType(data) {
+  Object.assign(this, data);
+}
+
+Object.defineProperty(UserType.prototype, 'extract', {
+  get() { return () => utils.extract(this); }
+});
+
+const User = define('User', UserType);
+const user = new User({ name: 'Ada' });
+user.extract(); // works
+```
 
 ## Internal Props System
 
 Instance metadata is stored externally via `WeakMap` against the prototype object,
 not the instance itself. This keeps instance enumeration clean — internal props
-never show up in `for...in`, `Object.keys`, or `JSON.stringify`.
+never show up in `for...in`, `Object.keys()`, or `JSON.stringify()`.
 
 ```typescript
 const props = getProps(instance);

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/.ai/rules-skill/type-system.md

@@ -26,7 +26,8 @@ type UserData = { name: string; age: number; };
 // ❌ WRONG - Instance is NOT an interface!
 interface UserData { name: string; age: number; }
 
-// ✅ CORRECT - Constructor/Prototype contract uses INTERFACE
+// ✅ CORRECT - Constructor/Prototype contract uses INTERFACE (when attaching
+// legacy instance methods to the prototype before define())
 interface MnemonicaInstance {
     extract(): Record<string, unknown>;
     parent(): object | undefined;
@@ -78,7 +79,7 @@ from (prototype, arguments, config). The resulting constructor is simultaneously
 
 - a runtime value (callable, `new`-able, with `.prototype`)
 - a node in the type Trie (carries `.subtypes`, participates in `instanceof`)
-- a behavioral contract (the prototype chain provides `.extract()`, `.fork()`, etc.)
+- a behavioral contract (the prototype chain provides the user's own properties; legacy instance methods must be attached explicitly if desired)
 
 Augmented to user-specific types via a `TypeRegistry` declaration-merge — hand-written or generated by tactica.
 
@@ -112,3 +113,12 @@ const AdminType = UserType.define('AdminType', function (this: AdminType) {
     this.role = 'admin';
 });
 ```
+
+## Generic Public Utilities
+
+The standalone utilities in `utils` infer their type parameters from the instance
+argument. Callers should never need an explicit `<T>` cast for ordinary operations.
+
+The full reference — helper types (`Extracted`, `Merge`, `InstanceResult`,
+`Parsed`, `SiblingAccessor`), every utility signature, and the type-level
+explanation of `utils.merge` — lives in [`docs/UTILS.md`](../../docs/UTILS.md).

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.**
@@ -78,6 +78,8 @@ npm run watch          # watch mode
 
 **Must run `npm run test:cov` before completing any task.**
 
+**Documentation changes:** When modifying any `.md` file, `npm run lint:md` is mandatory. It checks for broken links and anchors. Run it and fix any reported issues before finishing.
+
 ## Code Style (Project-Specific)
 
 See [`.ai/rules-skill/code-style.md`](./.ai/rules-skill/code-style.md) for the full style reference. Key rules: tabs only, space before function parens, colons aligned in object literals, `strict: true`, **no `any`** (`no-explicit-any: error`).
@@ -90,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] | undefined;
+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:
@@ -114,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.
 
@@ -172,9 +180,11 @@ For test passing confirmations (e.g., `npm run test:cov`), checking the end of t
 
 These configuration files define the project's strict standards. Any changes require user approval first.
 
-## Return Statement Design Rule
+## Return Statement Design Rule (Non-negotiable)
+
+**Every return expression must go through an intermediate variable/constant.** No exceptions. This is critical for debuggability with `npm run debug` and Chrome Dev Tools — when execution pauses on `return result`, you can hover your mouse over `result` and inspect the value. With `return SomeFn(arg)`, the value is gone before the debugger can show it.
 
-**Always use an intermediate variable before returning.** This is critical for debuggability with `npm run debug` and Chrome Dev Tools.
+**This rule is enforced. If you write `return new Foo()` or `return fn()`, the PR will be rejected.**
 
 ### Prohibited patterns:
 ```typescript

package/CONTRIBUTING.md

@@ -26,6 +26,12 @@ npm run test:jest:cov
 `src/` → `build/`. To run linters with auto-fix, use `npm run lint:fix`.
 To run linters in read-only mode (CI parity), use `npm run lint:check`.
 
+### Doc-only changes
+
+If your change touches only Markdown files (no `src/`, `test/`, `test-jest/`,
+`test-ts/`, or build config), you can **skip `npm run build` and the test
+suites**. Run `npm run lint:md` to catch dead links and broken anchors instead.
+
 ## Test frameworks
 
 There are two suites and both must stay green:
@@ -45,9 +51,9 @@ 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 exposeInstanceMethods default
+docs: clarify instance method opt-in pattern
 chore(ci): bump setup-node to v4
 ```