mnemonica 0.9.99787 → 1.0.1

package/.ai/AGENTS.md

@@ -0,0 +1,138 @@
+# AI Agent Guidelines — mnemonica/core
+
+> **Framework-agnostic entry point for all AI agents.**
+> This directory is the authoritative source.
+
+---
+
+## What This Project Is
+
+**mnemonica** is an instance inheritance system for JavaScript / TypeScript.
+It enables prototype chain-based type definitions through the `define()`
+function, creating explicit inheritance graphs that eliminate common prototype
+bugs.
+
+Key insight: JavaScript prototype inheritance is a Trie data structure, but
+developers don't realize this. Mnemonica forces explicit declaration of
+inheritance graphs, making certain classes of bugs impossible by design.
+
+---
+
+## Files in This Directory
+
+| File | Purpose |
+|------|---------|
+| [`AGENTS.md`](./AGENTS.md) | This file — main entry point and overview |
+| [`CODE.md`](./CODE.md) | Coding standards: style, TypeScript rules, testing |
+| [`ARCHITECT.md`](./ARCHITECT.md) | Design guidelines: patterns, planning, constraints |
+| [`DEBUG.md`](./DEBUG.md) | Debugging guidelines: commands, common issues, logging |
+| [`async_init.md`](./async_init.md) | Async class constructor support: wrapper pattern, `Symbol.hasInstance`, tests |
+| [`ask/AGENTS.md`](./ask/AGENTS.md) | Ask mode: explaining concepts, analyzing code |
+| [`orchestrator/AGENTS.md`](./orchestrator/AGENTS.md) | Orchestrator mode: multi-step task coordination |
+| [`rules/CODING.md`](./rules/CODING.md) | Extended coding rules: models vs controllers, raw* prefix, full file reading |
+| [`rules/REMINDERS.md`](./rules/REMINDERS.md) | Quick reference: type vs interface, spacing, before-task checklist |
+| [`rules/CONTEXT-CONDENSING.md`](./rules/CONTEXT-CONDENSING.md) | Recovery protocol when context condenses |
+| [`task-templates/`](./task-templates/) | Reusable task templates |
+
+---
+
+## Quick Start for Agents
+
+### First Time Here?
+
+Read [`ONBOARDING.md`](./ONBOARDING.md) — a single-file quickstart covering everything you need to know before touching code.
+
+### Before You Write Any Code
+
+1. Read [`CODE.md`](./CODE.md) — style rules, TypeScript rules, testing requirements.
+2. Read [`ARCHITECT.md`](./ARCHITECT.md) — design patterns and constraints.
+3. If debugging: read [`DEBUG.md`](./DEBUG.md).
+4. If working with async constructors: read [`../docs/async-constructors.md`](../docs/async-constructors.md) — the `super()` return-value pattern and native async class wrapping.
+
+### Build & Test Commands
+
+```bash
+# Full build with linting
+npm run build
+
+# Run Mocha tests with coverage (runs npm run build:all internally)
+npm run test:cov
+
+# Run Jest tests with coverage (TypeScript source)
+npm run test:jest:cov
+
+# Watch mode
+npm run watch
+```
+
+**Critical**: `npm run test:cov` runs `npm run build:all` internally. You do
+not need to run `npm run build` first.
+
+**Must run `npm run test:cov` before completing any task** — this validates
+build and ensures 100% coverage.
+
+---
+
+## Architecture at a Glance
+
+```
+src/
+├── index.ts           # Main exports: define, lookup, apply, call, bind
+├── types/index.ts     # TypeScript type definitions
+├── constants/         # Symbols and default options
+├── descriptors/       # Type collection and error definitions
+├── api/               # Core implementation
+│   ├── types/         # TypeProxy, InstanceCreator, Mnemosyne
+│   ├── errors/        # Error handling and stack traces
+│   ├── hooks/         # Lifecycle hooks
+│   └── utils/         # Utilities
+└── utils/             # Public utilities (extract, parse, merge, etc.)
+```
+
+### Proxy-Based Architecture
+
+- **TypeProxy** (`src/api/types/TypeProxy.ts`): Wraps type constructors
+- **Mnemosyne** (`src/api/types/Mnemosyne.ts`): Handles instance method access
+- **TypesCollection Proxy** (`src/descriptors/types/index.ts`): Dynamic type lookup
+
+### Key Symbols
+
+| Symbol | Purpose |
+|--------|---------|
+| `SymbolConstructorName` | Stores type name on constructors |
+| `SymbolParentType` | Links to parent type |
+| `SymbolDefaultTypesCollection` | Default collection identifier |
+| `SymbolConfig` | Type configuration storage |
+
+---
+
+## How Agents Discover These Docs
+
+Based on observed agent behavior:
+
+| What agents do | Result |
+|----------------|--------|
+| Read `README.md` first | Usually discovers the `.ai/` pointer |
+| Read `package.json` second | Learns scripts, dependencies |
+| Read source code third | Infers architecture from implementation |
+| Skip `AGENTS.md` unless told | Often misses build rules, style constraints |
+
+**If you are an agent reading this:** You likely arrived via `README.md` → `AGENTS.md` → `.ai/AGENTS.md`. Good path. Now read `ONBOARDING.md` for the condensed version, or `CODE.md` + `ARCHITECT.md` for full detail.
+
+**If you are a human:** These docs are for AI agents. The human-facing docs live in `docs/`.
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| [`../SKILL.md`](../SKILL.md) | Condensed skill reference for framework injection |
+| [`../AGENTS.md`](../AGENTS.md) | Root agent guidelines |
+| [`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 |
+| [`../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/ARCHITECT.md

@@ -0,0 +1,110 @@
+# Design Guidelines — mnemonica/core
+
+> **Applies to:** Planning, designing, and strategizing changes without modifying
+> implementation files. Framework-agnostic.
+
+---
+
+## Role
+
+You are in **Architect** mode. Your task is to plan, design, and strategize
+changes to the mnemonica codebase without modifying implementation files.
+
+---
+
+## Project Overview
+
+Mnemonica is an **instance inheritance system** using JavaScript prototype
+chains. It allows creating type hierarchies where instances can spawn child
+instances that inherit from parent instances.
+
+### Core Concept
+
+```typescript
+// Define types
+const User = define('User', function (name: string) {
+	this.name = name;
+});
+
+// Create parent instance
+const user = new User('John');
+
+// Create child instance inheriting from parent
+const admin = user.Admin('admin privileges');
+// admin inherits all User properties + new Admin properties
+```
+
+---
+
+## Architecture Patterns
+
+### Proxy-Based Design
+
+```
+TypeProxy → wraps constructor functions
+Mnemosyne → handles instance prototype chain
+TypesCollection → manages type registry
+```
+
+### Internal Instance Properties
+
+```typescript
+interface InstanceInternalProps {
+	[SymbolConstructorName]: string;      // Type name
+	[SymbolParentType]: object;            // Parent instance
+	[SymbolSubTypes]: Map<string, object>; // Child types
+}
+```
+
+### Symbol System
+
+See [`AGENTS.md`](./AGENTS.md) for the complete symbol reference table.
+
+---
+
+## Design Principles
+
+### Type Safety
+- Strict TypeScript with `strict: true`
+- All functions must have explicit return types
+- Types must be complete and reusable
+- **No `any`** (`@typescript-eslint/no-explicit-any: error`) — define proper types
+- Never use bare `Function`, `CallableFunction`, or `NewableFunction` — define purpose-specific interfaces
+
+### Proxy Handler Design
+
+```typescript
+// Pattern for proxy handlers
+type ProxyHandler<T> = {
+	get?(target: T, prop: string, receiver: unknown): unknown;
+	set?(target: T, prop: string, value: unknown, receiver: unknown): boolean;
+	apply?(target: T, thisArg: unknown, args: unknown[]): unknown;
+};
+```
+
+### Extension Points
+
+1. **Types** — Create via `define()` function
+2. **Hooks** — Register with `registerHook()`
+3. **Flow Checkers** — Add validation with `registerFlowChecker()`
+4. **Subtypes** — Extend types with `type.define()`
+
+---
+
+## Documentation Format
+
+When creating design documents:
+1. Use `.md` extension only
+2. Include code examples in TypeScript
+3. Reference existing patterns from `src/types/index.ts`
+4. Document symbol usage and meanings
+
+---
+
+## Constraints
+
+- **Do not** write implementation code (`*.ts` files)
+- **Do not** modify existing source files
+- Focus on `.md` documentation and planning
+- Consider 100% test coverage requirement
+- Respect the dual test framework (Mocha + Jest)

package/.ai/CODE.md

@@ -0,0 +1,111 @@
+# Coding Standards — mnemonica/core
+
+> **Applies to:** All code changes. Framework-agnostic.
+> See also `.ai/rules/CODING.md` for extended coding rules.
+
+---
+
+## Build & Test Commands
+
+See [`rules-skill/testing.md`](./rules-skill/testing.md) for the full reference. Summary:
+```bash
+npm run build          # full build with linting
+npm run test:cov       # Mocha + coverage (runs build:all internally)
+npm run test:jest:cov  # Jest on TypeScript source
+npm run watch          # watch mode
+```
+**Must run `npm run test:cov` before completing any task.**
+
+---
+
+## Code Style Rules
+
+See [`rules-skill/code-style.md`](./rules-skill/code-style.md) for the full style guide (tabs, function spacing, aligned colons, TypeScript strictness, no `any`).
+
+The return-statement rule is design-critical and is documented in full in [`../AGENTS.md`](../AGENTS.md#return-statement-design-rule). Summary: **always use an intermediate variable before returning** so Chrome DevTools can inspect the value at a breakpoint.
+
+---
+
+## TypeScript Type Rules
+
+**Never use bare `Function`, `CallableFunction`, or `NewableFunction` as parameter or return types.** Define a purpose-specific interface that extends them. See [`rules-skill/code-style.md`](./rules-skill/code-style.md) for examples and allowed exceptions.
+
+---
+
+## Build Output Inspection
+
+When running `npm run build` or `npm run build:all`, **check the beginning of the output** for errors and warnings. Build failures (TypeScript compilation errors, ESLint issues, etc.) often appear at the start of the output. Do not rely only on the end of the output or `tail` for build status.
+
+For test passing confirmations (e.g., `npm run test:cov`), checking the end of the output is acceptable.
+
+---
+
+## Type Patterns
+
+### Proxy Handlers
+```typescript
+type ProxyHandler<T> = {
+	get?(target: T, prop: string, receiver: unknown): unknown;
+	set?(target: T, prop: string, value: unknown, receiver: unknown): boolean;
+};
+```
+
+### Internal Instance Properties
+```typescript
+interface MnemonicaInstance {
+	[SymbolConstructorName]?: string;
+	[SymbolParentType]?: object;
+	[SymbolSubTypes]?: Map<string, object>;
+}
+```
+
+---
+
+## Testing Requirements
+
+See [`rules-skill/testing.md`](./rules-skill/testing.md) for full details. 100% coverage required on both Mocha and Jest. Jest tests should mirror Mocha patterns from `test/environment.js`.
+
+---
+
+## Symbols Reference
+
+See [`AGENTS.md`](./AGENTS.md) for the complete symbol reference table.
+
+---
+
+## Adding Type Definitions
+
+```typescript
+// 1. Define type in src/types/index.ts
+export interface NewTypeConfig {
+	property: string;
+}
+
+// 2. Update existing interfaces if needed
+export interface MnemonicaInstance {
+	newProperty?: NewTypeConfig;
+}
+```
+
+---
+
+## Error Handling
+
+```typescript
+// Use MnemonicaErrorConstructor for custom errors
+import { constructError } from '../api/errors/index.js';
+
+const MyError = constructError('MY_ERROR', 'Error message');
+throw new MyError('additional info', stack);
+```
+
+---
+
+## Configuration Files
+
+**Disallowed without explicit approval:**
+- Modifying `./tsconfig.json`
+- Modifying `./eslint.config.js`
+
+These configuration files define the project's strict standards. Any changes
+require user approval first.

package/.ai/DEBUG.md

@@ -0,0 +1,179 @@
+# Debugging Guidelines — mnemonica/core
+
+> **Applies to:** Investigating issues, diagnosing problems, identifying root
+> causes. Framework-agnostic.
+
+---
+
+## Role
+
+You are in **Debug** mode. Your task is to investigate issues, diagnose problems,
+and identify root causes in the mnemonica codebase.
+
+---
+
+## Debug Commands
+
+```bash
+# Run tests with coverage to identify untested paths
+npm run test:cov
+
+# Run Jest with verbose output
+npm run test:jest -- --verbose
+
+# Run specific test file
+npx jest test-jest/types.ts --verbose
+
+# Run Mocha with debug output
+DEBUG=* npm test
+
+# Build and check for TypeScript errors
+npm run build
+```
+
+### Build Output Inspection
+
+When running `npm run build` or `npm run build:all`, **check the beginning of the
+output** for errors and warnings. Build failures (TypeScript compilation errors,
+ESLint issues, etc.) often appear at the start of the output. Do not rely only on
+the end of the output or `tail` for build status.
+
+For test passing confirmations (e.g., `npm run test:cov`), checking the end of
+the output is acceptable.
+
+---
+
+## Common Issue Patterns
+
+### Proxy Handler Issues
+
+```typescript
+// If traps are not working, check:
+// 1. Handler methods return correct types
+// 2. `get` trap returns `unknown`, not implicit `any`
+// 3. `set` trap returns boolean, not void
+
+// Debug proxy behavior
+const debugProxy = new Proxy(target, {
+	get(target, prop, receiver) {
+		console.log('Getting:', prop);
+		return Reflect.get(target, prop, receiver);
+	}
+});
+```
+
+### Type Errors
+
+```typescript
+// Common: 'any' type assignment
+// Fix: Add proper type annotation
+const value: SpecificType = unknownValue as SpecificType;
+
+// Common: missing 'this' type
+// Fix: Add explicit this parameter
+function method(this: SpecificType) { }
+```
+
+### Instance Chain Issues
+
+```typescript
+// Check instance properties
+console.log(instance[SymbolConstructorName]);
+console.log(instance[SymbolParentType]);
+console.log(instance[SymbolSubTypes]);
+
+// Verify prototype chain
+console.log(Object.getPrototypeOf(instance));
+```
+
+---
+
+## Logging Strategy
+
+### Add Temporary Logging
+
+```typescript
+// In proxy handlers
+get(target, prop, receiver) {
+	console.log(`[Proxy.get] prop: ${String(prop)}`);
+	// ... existing code
+}
+
+// In error constructors
+constructor(message, additionalStack) {
+	console.log('[Error]', message, additionalStack);
+	// ... existing code
+}
+```
+
+### Stack Trace Analysis
+
+```typescript
+// Use error stack cleaners
+import { cleanupStack } from '../api/errors/index.js';
+
+const cleaned = cleanupStack(stack.split('\n'));
+console.log('Cleaned stack:', cleaned);
+```
+
+---
+
+## Symbol Debugging
+
+```typescript
+// Inspect instance symbols
+const symbols = Object.getOwnPropertySymbols(instance);
+symbols.forEach(sym => {
+	console.log(sym.toString(), ':', (instance as Record<symbol, unknown>)[sym]);
+});
+```
+
+---
+
+## Test Debugging
+
+### Mocha Tests
+
+```bash
+# Run single test suite
+npx mocha build/test-ts/test-example.js
+
+# With debug output
+DEBUG=mnemonica npx mocha build/test-ts/test-example.js
+```
+
+### Jest Tests
+
+```bash
+# Run with debugger
+node --inspect-brk node_modules/.bin/jest --runInBand test-jest/types.ts
+
+# With console output
+npx jest test-jest/types.ts --verbose --no-coverage
+```
+
+---
+
+## Issue Checklist
+
+1. [ ] Check TypeScript compilation: `npm run build`
+2. [ ] Check build output **at the beginning** for errors/warnings (not just tail)
+3. [ ] Run Mocha tests: `npm run test:mocha`
+4. [ ] Run Jest tests: `npm run test:jest`
+5. [ ] Check test coverage: `npm run test:cov`
+6. [ ] Verify indentation (tabs not spaces)
+7. [ ] Check for bare `Function` / `CallableFunction` / `NewableFunction` types
+8. [ ] Verify symbol usage is correct
+9. [ ] Check proxy handler return types
+10. [ ] Verify return statements use intermediate variables
+
+---
+
+## Reporting Issues
+
+When reporting findings:
+1. Include file paths and line numbers
+2. Show relevant code snippets
+3. Provide error messages in full
+4. Suggest root cause, not just symptoms
+5. Reference related test files

package/.ai/ONBOARDING.md

@@ -0,0 +1,171 @@
+# Onboarding — New Agent Quickstart
+
+> **Read this first.** One file. Five minutes. Everything you need to contribute to mnemonica without reading 8+ files.
+
+---
+
+## What Is mnemonica?
+
+An **instance inheritance system** for JavaScript/TypeScript. You define types with `define()` and create instances that inherit through prototype chains — not just classes, but between instances.
+
+```typescript
+const User = define('User', function (this: UserData, data: UserData) {
+	Object.assign(this, data);
+});
+
+const user  = new User({ name: 'John' });
+const admin = new user.Admin({ role: 'admin' }); // inherits from user instance
+```
+
+**Scope:** mnemonica types the data flow, not the control flow. It gives data memory of its own creation (type, parent, arguments, timestamp) but does not dictate how services, algorithms, or control flow work. Keep behavior code intact; mnemonica only replaces plain data objects with typed instances.
+
+**The greater view.** mnemonica does not add a new abstraction on top of JavaScript — it makes an existing one explicit. The prototype chain is already a Trie; every `new` already extends a node. `new user.Admin()` is not a library call — it is JavaScript's prototype mechanism used deliberately. mnemonica names each node, stores the construction arguments at each step, and makes the chain queryable. The thing you have been building with manually all along, made first-class.
+
+**Why not class hierarchies?** Class inheritance shares `Admin.prototype` across all instances. Two concurrent requests both creating `Admin` instances share the same prototype. `new user.Admin()` creates a chain where `user` IS the prototype — each pipeline run is isolated structurally, not by convention.
+
+**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.
+
+---
+
+## Build & Test
+
+```bash
+# Install dependencies
+npm ci
+
+# Build TypeScript
+npm run build
+
+# Run Mocha tests with coverage (runs build:all internally)
+npm run test:cov
+
+# Run Jest tests with coverage (TypeScript source, faster)
+npm run test:jest:cov
+
+# Watch mode
+npm run watch
+```
+
+**Rule:** `npm run test:cov` before completing any task. It validates the build and ensures 100% coverage.
+
+**Build tip:** Check the **beginning** of build output for errors. For tests, the end is fine.
+
+---
+
+## Code Style (Non-Negotiable)
+
+### Indentation
+- **TABS ONLY** — never spaces. Tab width: 4.
+
+### Function Spacing
+```typescript
+function myFunc () { }     // ✓ space before paren
+function myFunc() { }      // ✗ wrong
+```
+
+### Return Statements
+**Always use an intermediate variable before returning.**
+
+```typescript
+// ✓ GOOD — inspectable in debugger
+const result = { target, name };
+return result;
+
+// ✗ BAD — can't inspect
+return { target, name };
+```
+
+### TypeScript Types
+- `strict: true`, `noUnusedLocals: true`, `noUnusedParameters: true`
+- **No `any`** (`@typescript-eslint/no-explicit-any: error`) — use purpose-specific interfaces
+- **Never** use bare `Function`, `CallableFunction`, or `NewableFunction` — define purpose-specific interfaces
+
+---
+
+## Architecture
+
+```
+src/
+├── index.ts           # Main exports: define, lookup, apply, call, bind
+├── types/index.ts     # TypeScript type definitions
+├── constants/         # Symbols and default options
+├── descriptors/       # Type collection and error definitions
+├── api/               # Core implementation
+│   ├── types/         # TypeProxy, InstanceCreator, Mnemosyne
+│   ├── errors/        # Error handling and stack traces
+│   ├── hooks/         # Lifecycle hooks
+│   └── utils/         # Utilities
+└── utils/             # Public utilities (extract, parse, merge, etc.)
+```
+
+Key components:
+- **TypeProxy** — wraps type constructors
+- **InstanceCreator** — orchestrates construction lifecycle
+- **Mnemosyne** — handles instance method access via Proxy
+
+---
+
+## Testing Rules
+
+- **Dual framework:** Mocha (transpiled `build/`), Jest (TypeScript `src/`)
+- **100% coverage** required for both
+- Jest tests should mirror Mocha patterns from `test/environment.js`
+- Tests must pass with `--allow-uncaught` (mocha)
+
+---
+
+## Async Constructors
+
+mnemonica supports async constructors natively:
+
+```typescript
+const AsyncType = define('AsyncType', async function () {
+	await sleep(100);
+	this.done = true;
+	return this; // MUST return with awaitReturn: true (default)
+});
+
+const instance = await new AsyncType();
+```
+
+**Critical:** Async subtypes are invoked as methods on the parent instance:
+
+```typescript
+const parent = await new AsyncParent();
+const child = await parent.AsyncChild(); // ✓ correct
+
+const wrong = await new AsyncChild();    // ✗ fails strictChain
+```
+
+Read [`../docs/async-constructors.md`](../docs/async-constructors.md) for the `super()` return-value trap and native async class wrapping.
+
+---
+
+## Common Pitfalls
+
+1. **`await new AsyncSubType()`** — wrong. Use `await parent.AsyncSubType()`.
+2. **`return { a, b }`** — wrong. Use `const result = { a, b }; return result;`.
+3. **Modifying `tsconfig.json` or `eslint.config.js`** — forbidden without explicit approval.
+4. **Forgetting `npm run test:cov`** — always run before finishing.
+5. **Using `Function` as a type** — define `interface MyHandler extends CallableFunction { ... }`.
+
+---
+
+## Where to Go Next
+
+| Need | Read |
+|------|------|
+| Coding standards, type rules | [`CODE.md`](./CODE.md) |
+| Design patterns, constraints | [`ARCHITECT.md`](./ARCHITECT.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) |
+| Behavioral guidelines | [`rules-skill/contributing.md`](./rules-skill/contributing.md) |
+| Explaining code (ask mode) | [`ask/AGENTS.md`](./ask/AGENTS.md) |
+| Multi-step coordination | [`orchestrator/AGENTS.md`](./orchestrator/AGENTS.md) |
+
+---
+
+> **This file is a summary.** For authoritative rules, read the linked files. For the full type system, read `src/types/index.ts`.