mnemonica 1.0.0 → 1.0.6

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.
 
 ---
 

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/async_init.md

@@ -4,7 +4,7 @@
 
 JavaScript class constructors cannot be declared `async`. However, a constructor **can return a Promise**. When a base class constructor returns `Promise.resolve(this)`, the subclass `this` becomes the Promise object — class fields initialize on the Promise wrapper, not the real instance. This breaks field inheritance in raw JS.
 
-Mnemonica handles this correctly through its wrapper architecture. See also the [abstract demonstration](../../async_test/README.md) showing the problem and wrapper fix in library-agnostic terms.
+Mnemonica handles this correctly through its wrapper architecture. See also the [test suite](../test_async/index.js) showing the problem and wrapper fix in practice.
 
 ## How Mnemonica Preserves Class Fields
 
@@ -89,6 +89,6 @@ Tests live in `test_async/index.js` and run via `npm run test:async_init`.
 
 ## Related
 
-- [Abstract async test demonstration](../../async_test/README.md) — library-agnostic explanation of the problem and wrapper fix
+- [`test_async/index.js`](../test_async/index.js) — test suite covering async initialization scenarios
 - [TC39 proposal-async-init issue #3](https://github.com/tc39/proposal-async-init/issues/3) — language-level discussion of the same problem
 - [Mnemonica README](../README.md) — project overview and API documentation

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

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/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

@@ -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`).
@@ -172,9 +174,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:
@@ -47,7 +53,7 @@ Conventional commits are preferred:
 ```
 feat: add lookupTyped 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
 ```
 
@@ -100,13 +106,59 @@ Per [AGENTS.md](AGENTS.md):
 - The build must produce **zero** ESLint warnings on `./src` — fix the
   source, do not relax the rules.
 
+## Keeping docs consistent
+
+When adding or renaming a file, update any `.md` files that link to it.
+When adding a new concept or section, check whether an existing doc already
+covers it — prefer extending one place over splitting the explanation across
+two. Run `npm run lint:md` before committing doc changes; it catches dead
+links and broken anchors across all Markdown files in the repo.
+
 ## Releasing
 
-1. Update release notes.
-2. Bump `version` in `package.json`.
-3. `npm run verify` (build + lint:check).
-4. `npm run test:cov && npm run test:jest:cov` (both 100% coverage).
-5. `npm pack --dry-run` and verify the tarball includes `build/`,
-   `module/`, `README.md`, `LICENSE`, and does **not** include
-   `test/decorate.js` or `test/example.js`.
-6. Tag and publish.
+### 1. Update the changelog
+
+In `CHANGELOG.md`, move everything under `## [Unreleased]` into a
+new versioned section:
+
+```markdown
+## [1.0.1] - 2026-05-22
+
+### Fixed
+- ...
+```
+
+Leave a fresh empty `## [Unreleased]` block at the top for the next cycle.
+
+### 2. Bump the version
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1
+# or: minor (1.0.0 → 1.1.0)  major (1.0.0 → 2.0.0)
+```
+
+`npm version` updates `package.json` and creates a git commit + tag
+(`v1.0.1`) automatically. Do not edit `package.json` by hand for this.
+
+### 3. Verify
+
+```bash
+npm run verify                               # build + lint:check
+npm run test:cov && npm run test:jest:cov    # both suites, 100% coverage
+npm run lint:md                              # no dead links or broken anchors
+```
+
+All three must pass before publishing.
+
+### 4. Inspect the tarball
+
+```bash
+npm pack --dry-run
+```
+
+The tarball must include: `build/`, `module/`, `src/`, `docs/`, `.ai/`,
+`examples/`, `README.md`, `FOR_HUMANS.md`, `AGENTS.md`, `SKILL.md`,
+`CONTRIBUTING.md`, `LICENSE`.
+
+It must **not** include: `test/`, `test-jest/`, `test-ts/`, `test_async/`,
+`reports/`, `.husky/`, `node_modules/`.