@mnemonica/tactica 0.1.0 → 0.1.1

package/README.md

@@ -1,14 +1,20 @@
 # @mnemonica/tactica
 
-**TypeScript Language Service Plugin for Mnemonica**
+**Type definition generator for Mnemonica.**
 
-Tactica generates type definitions for Mnemonica's dynamic nested constructors, enabling TypeScript to understand runtime type hierarchies created through `define()` and `decorate()` calls.
+Tactica is a CLI tool and Node library that statically analyzes TypeScript / JavaScript source code and generates type definitions, navigation metadata, and runtime-flow data for projects that use [mnemonica](https://github.com/wentout/mnemonica) — the instance-inheritance system that creates types dynamically at runtime through `define()` and `decorate()` calls.
+
+Output lives in `.tactica/` and is consumed by:
+
+- **`tsc`** — so TypeScript can understand `user.AdminType` after `UserType.define('AdminType', …)`.
+- **`mnemonica.lookupTyped<K>()`** — type-safe runtime lookup via the generated `TypeRegistry` module augmentation.
+- **[mnemographica](https://github.com/mythographica/mnemographica)** (VS Code extension) — for Go to Definition, Find References, and the type-hierarchy graph view.
 
 ## The Problem
 
-Mnemonica enables powerful instance-level inheritance:
+Mnemonica enables instance-level inheritance:
 
-```typescript
+```ts
 const UserType = define('UserType', function (this: { name: string }) {
     this.name = '';
 });
@@ -18,14 +24,14 @@ const AdminType = UserType.define('AdminType', function (this: { role: string })
 });
 
 const user = new UserType();
-const admin = new user.AdminType(); // Works at runtime!
+const admin = new user.AdminType(); // works at runtime
 ```
 
-But TypeScript doesn't know that `user.AdminType` exists because `UserType.define()` is a runtime operation.
+TypeScript can't infer that `user.AdminType` exists, because `UserType.define()` is a runtime operation.
 
 ## The Solution
 
-Tactica analyzes your TypeScript source files and generates declaration files that tell TypeScript about the nested constructor hierarchy.
+Tactica parses your source, builds the type hierarchy, and emits `.tactica/types.ts` + `.tactica/registry.ts`. Once those files are part of your `tsc` compilation, TypeScript understands the full hierarchy — without runtime changes.
 
 ## Installation
 
@@ -33,60 +39,29 @@ Tactica analyzes your TypeScript source files and generates declaration files th
 npm install --save-dev @mnemonica/tactica
 ```
 
-## Usage
-
-### 1. As a TypeScript Language Service Plugin (Recommended)
-
-Add to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "plugins": [
-      {
-        "name": "@mnemonica/tactica",
-        "outputDir": ".tactica",
-        "include": ["src/**/*.ts"],
-        "exclude": ["**/*.test.ts", "**/*.spec.ts"]
-      }
-    ]
-  }
-}
-```
-
-Then include the generated types in your project:
-
-```json
-{
-  "compilerOptions": {
-    "typeRoots": ["./node_modules/@types", "./.tactica"]
-  }
-}
-```
+`mnemonica` is a peer dependency (>= 1.0.1).
 
-### 2. As a CLI Tool
+## Usage
 
-Generate types once:
+### CLI
 
 ```bash
+# One-shot generation
 npx tactica
-```
-
-Watch mode for development:
 
-```bash
+# Watch mode (regenerate on file changes)
 npx tactica --watch
-```
 
-With custom options:
+# Custom output directory
+npx tactica --output ./types/mnemonica
 
-```bash
-npx tactica --project ./src/tsconfig.json --output ./types/mnemonica
+# Custom tsconfig
+npx tactica --project ./src/tsconfig.json
 ```
 
-### 3. As a Module
+### Library
 
-```typescript
+```ts
 import { MnemonicaAnalyzer, TypesGenerator, TypesWriter } from '@mnemonica/tactica';
 import * as ts from 'typescript';
 
@@ -100,112 +75,155 @@ for (const sourceFile of program.getSourceFiles()) {
 }
 
 const generator = new TypesGenerator(analyzer.getGraph());
+const writer    = new TypesWriter('.tactica');
 
-// Generate types.ts (exportable type aliases - default mode)
-const generatedTypes = generator.generateTypesFile();
-const writer = new TypesWriter('.tactica');
-writer.writeTypesFile(generatedTypes);
+// Default mode — exportable type aliases in types.ts + a TypeRegistry augmentation in registry.ts.
+writer.writeTypesFile(generator.generateTypesFile());
+writer.writeTo('registry.ts', generator.generateTypeRegistry().content);
 
-// Or generate index.d.ts (global augmentation - legacy mode)
-const generatedGlobal = generator.generateGlobalAugmentation();
-writer.writeGlobalAugmentation(generatedGlobal);
+// Legacy mode — single global augmentation file index.d.ts.
+// writer.writeGlobalAugmentation(generator.generateGlobalAugmentation());
 ```
 
-## Configuration Options
+### Project setup
 
-### Plugin Options (tsconfig.json)
+After running `npx tactica`, add `.tactica` to your `tsconfig.json` so the generated files are part of the compilation:
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `outputDir` | string | `.tactica` | Directory for generated types |
-| `include` | string[] | `['**/*.ts']` | File patterns to include |
-| `exclude` | string[] | `['**/*.d.ts']` | File patterns to exclude |
-| `verbose` | boolean | `false` | Enable verbose logging |
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "~tactica/*": ["./.tactica/*"]
+    }
+  },
+  "include": ["src/**/*.ts", ".tactica/**/*.ts"]
+}
+```
+
+Then use `lookupTyped` for type-safe access (see "Type-Safe Lookup" below).
 
-### CLI Options
+You should commit `.tactica/` if you want type information to flow through CI without re-running tactica; alternatively, add `.tactica/` to `.gitignore` and regenerate as part of your build. Tactica does **not** modify `.gitignore` for you.
+
+## CLI Options
 
 | Option | Short | Description |
-|--------|-------|-------------|
-| `--watch` | `-w` | Watch mode - regenerate on file changes |
-| `--project` | `-p` | Path to tsconfig.json |
-| `--output` | `-o` | Output directory (default: `.tactica`) |
-| `--include` | `-i` | Include patterns (comma-separated) |
-| `--exclude` | `-e` | Exclude patterns (comma-separated) |
-| `--module-augmentation` | `-m` | Generate global augmentation (legacy mode) |
-| `--verbose` | `-v` | Enable verbose logging |
-| `--help` | `-h` | Show help message |
-
-**Examples:**
+|---|---|---|
+| `--watch` | `-w` | Watch mode — regenerate on file changes |
+| `--project <path>` | `-p` | Path to `tsconfig.json` (default: nearest ancestor) |
+| `--output <dir>` | `-o` | Output directory (default: `.tactica`) |
+| `--include <patterns>` | `-i` | Comma-separated include patterns |
+| `--exclude <patterns>` | `-e` | Comma-separated exclude patterns |
+| `--topologica <dirs>` | `-t` | Comma-separated Topologica directories to scan |
+| `--module-augmentation` | `-m` | Legacy mode — emit a single global-augmentation `index.d.ts` instead of `types.ts` + `registry.ts` |
+| `--esm` |  | Append `.js` extensions to relative imports in generated files (for ESM / NodeNext module resolution) |
+| `--eds` |  | Force-enable EDS (Execution Data Storage) tracking |
+| `--no-eds` |  | Force-disable EDS tracking |
+| `--verbose` | `-v` | Verbose logging |
+| `--help` | `-h` | Show help |
+
+EDS tracking is **auto-enabled** when `@mnemonica/dive` is present in `package.json` dependencies; otherwise it is off. `--eds` / `--no-eds` override the auto-detection.
+
+## Generated Files
+
+Tactica writes everything under the `--output` directory (default `.tactica/`):
+
+| File | When | Purpose |
+|---|---|---|
+| `types.ts` | default mode | Exportable type aliases — one per discovered type. Uses `ProtoFlat<Parent, Self>` for nested types. |
+| `registry.ts` | default mode | `declare module 'mnemonica' { interface TypeRegistry { … } }` augmentation — powers `lookupTyped<K>()`. |
+| `index.ts` | default mode | Re-exports everything from `types.ts` and `registry.ts`. |
+| `index.d.ts` | with `--module-augmentation` | Single global-augmentation file (legacy mode). |
+| `definitions.json` | always | One entry per discovered type: `{ name, location, kind: 'define'\|'decorate', parent, strictChain, blockErrors }`. Consumed by `mnemographica`'s Go to Definition. |
+| `usages.json` | always | One entry per type, value is an array of `{ location, kind, code }` records — where each type is instantiated, referenced, accessed, or looked up. Consumed by `mnemographica`'s Find References. |
+| `flow.json` | always | Native instance-flow patterns (property reads/writes, method calls, destructuring, returns, spreads, etc.) per type. |
+| `eds.json` | when EDS enabled | Execution-flow patterns (`wrap`, `link`, `getLastContext`, hook attachment, framework adapters). Consumed by tools that visualize execution chains. |
+
+### Default mode (types.ts + registry.ts)
+
+```ts
+// .tactica/types.ts
+export type UserType = {
+    name: string;
+    email: string;
+    AdminType: new (data: { role: string }) => UserType_AdminType;
+};
 
-```bash
-# Default mode - generates .tactica/types.ts
-npx tactica
+export type UserType_AdminType = ProtoFlat<UserType, {
+    role: string;
+    AdminType: undefined;
+}>;
+```
 
-# Global augmentation mode - generates .tactica/index.d.ts
-npx tactica --module-augmentation
+```ts
+// .tactica/registry.ts
+declare module 'mnemonica' {
+    interface TypeRegistry {
+        'UserType': new (data: { name: string; email: string }) => UserType;
+        'UserType.AdminType': new (data: { role: string }) => UserType_AdminType;
+    }
+}
+```
+
+**Recommended for new projects.** Explicit imports, better tree-shaking, no global namespace pollution.
 
-# Watch mode with custom output directory
-npx tactica --watch --output ./custom-types
+### Legacy global-augmentation mode (`--module-augmentation`)
 
-# Exclude test files
-npx tactica --exclude "*.test.ts,*.spec.ts"
+Emits one `.tactica/index.d.ts` whose contents live inside `declare global { … }`. Reference it from your code with:
+
+```ts
+/// <reference types="./.tactica/index" />
 ```
 
-## Generated Output
+or by adding `./.tactica` to `compilerOptions.typeRoots`. Kept for backwards compatibility with older tactica integrations.
 
-By default, Tactica generates `.tactica/types.ts` with exported type aliases:
+## Type-Safe Lookup with `lookupTyped()`
 
-```typescript
-// Generated by @mnemonica/tactica - DO NOT EDIT
-export type UserTypeInstance = {
-    name: string;
-    email: string;
-    AdminType: TypeConstructor<AdminTypeInstance>;
-}
+Mnemonica core exposes `lookupTyped<K>()` against an empty `TypeRegistry` interface. Tactica's `registry.ts` augments that interface with all of your discovered types:
 
-export type AdminTypeInstance = UserTypeInstance & {
-    role: string;
-    permissions: string[];
+```ts
+// .tactica/registry.ts  (generated)
+declare module 'mnemonica' {
+    interface TypeRegistry {
+        'UserType': new (data: { name: string; email: string }) => UserType;
+        'UserType.AdminType': new (data: { role: string }) => UserType_AdminType;
+    }
 }
 ```
 
-### Output Modes
+Once `registry.ts` is in your `tsc` compilation, the lookup is fully typed:
 
-**Default mode** (`npx tactica`):
-- Generates `.tactica/types.ts` - Exportable type aliases
-- Import types explicitly: `import type { UserTypeInstance } from './.tactica/types'`
-- Include in tsconfig.json: `"include": ["src/**/*.ts", ".tactica/types.ts"]`
-- **Recommended for new projects** - explicit imports, better tree-shaking
+```ts
+import { lookupTyped } from 'mnemonica';
+import './.tactica/registry'; // or via tsconfig "include"
 
-**Global mode** (`npx tactica --module-augmentation`):
-- Generates `.tactica/index.d.ts` - Global type declarations
-- Types are available without imports (via `declare global`)
-- Add to tsconfig.json: `"typeRoots": ["./node_modules/@types", "./.tactica"]`
-- Use triple-slash reference: `/// <reference types="./.tactica/index" />`
+const UserType  = lookupTyped('UserType');
+const AdminType = lookupTyped('UserType.AdminType');
 
-**Choosing a mode:**
-- Use **Default mode** for new projects - explicit imports are clearer and work better with tree-shaking
-- Use **Global mode** if you want types available without imports (legacy behavior)
+const user  = new UserType({ name: 'John', email: 'j@x.dev' });
+const admin = new user.AdminType({ role: 'admin' });
+```
+
+No `as unknown as` casts required. See [`docs/lookupTyped-pattern.md`](docs/lookupTyped-pattern.md) for the consumer-side guide.
 
 ## What Gets Analyzed
 
-### 1. define() Calls
+### `define()` calls
 
-```typescript
-// Root type
-const UserType = define('UserType', function (this: { name: string }) {
+```ts
+const UserType  = define('UserType', function (this: { name: string }) {
     this.name = '';
 });
 
-// Nested type
 const AdminType = UserType.define('AdminType', function (this: { role: string }) {
     this.role = 'admin';
 });
 ```
 
-### 2. @decorate() Decorator
+Chained calls (`define('A').define('B')`) and nested calls via variable references (`const A = define('A', …); A.define('B', …)`) are both supported.
+
+### `@decorate()` decorator
 
-```typescript
+```ts
 @decorate()
 class User {
     name: string = '';
@@ -215,78 +233,57 @@ class User {
 class Admin {
     role: string = 'admin';
 }
-```
-
-#### Why Type Casting is Necessary for @decorate()
-
-When using `@decorate()` on classes, TypeScript cannot automatically infer that instances have nested type constructors (like `user.Admin`). This is because:
-
-1. **`define()` types work automatically**: When you use `define()`, the returned constructor has the correct type signature with nested constructors.
-
-2. **`@decorate()` classes need casting**: When you decorate a class, TypeScript sees the class itself, not the augmented type that mnemonica creates at runtime.
-
-**The Solution:** Cast to the instance type to access nested constructors:
-
-```typescript
-@decorate()
-class Order {
-    orderId: string = '';
-    total: number = 0;
-}
 
-@decorate(Order)
-class AugmentedOrder {
-    addition: string = 'extra';
+@decorate({ blockErrors: true, strictChain: false })
+class Configurable {
+    value: string = '';
 }
+```
 
-// Cast to OrderInstance to access AugmentedOrder constructor
-const order = new Order() as OrderInstance;
-const augmented = new order.AugmentedOrder(); // ✅ Works!
+Decorate-class instances need a cast to the generated instance type to access nested constructors at the type level:
 
-// The 'augmented' variable is automatically typed as AugmentedOrderInstance
-console.log(augmented.orderId);  // From Order
-console.log(augmented.addition); // From AugmentedOrder
+```ts
+const order = new Order() as Order_AugmentedOrder; // … or whatever your generated alias is
+const sub   = new order.AugmentedOrder();
 ```
 
-Generated types (like `OrderInstance`, `AugmentedOrderInstance`) are automatically available globally - no imports needed!
+### `Object.assign(this, data)` pattern
 
-#### @decorate() with Options
-
-```typescript
-@decorate({
-    blockErrors: true,
-    strictChain: false,
-    exposeInstanceMethods: true
-})
-class ConfigurableClass {
-    value: string = '';
-}
+```ts
+const UserType = define('UserType', function (this: any, data: { name: string }) {
+    Object.assign(this, data); // properties inferred from `data` type
+});
 ```
 
-### 3. Object.assign Pattern
+### `TypeConstructor` casting (from mnemonica)
 
-```typescript
-const UserType = define('UserType', function (this: any, data: any) {
-    Object.assign(this, data);
-});
+```ts
+import { define } from 'mnemonica';
+import type { TypeConstructor } from 'mnemonica';
+
+const MyFn = function (this: any) {
+    this.field = 123;
+} as TypeConstructor<{ field: number }>;
+
+const MyFnType = define('MyFnType', MyFn);
 ```
 
-### 4. Typeomatica Integration
+(In older mnemonica documentation this helper was called `ConstructorFunction`; the analyzer still recognizes that name in source code for back-compat.)
 
-Tactica works seamlessly with Typeomatica patterns:
+### Typeomatica integration
 
-```typescript
+Tactica recognizes [typeomatica](https://github.com/wentout/typeomatica) patterns alongside mnemonica:
+
+```ts
 import { decorate } from 'mnemonica';
 import { Strict, BaseClass } from 'typeomatica';
 
-// @Strict decorator alongside @decorate
 @decorate()
 @Strict({ someProp: 123 })
 class StrictDecorated {
     someProp!: number;
 }
 
-// BaseClass with Object.setPrototypeOf
 @decorate()
 class MyBaseClass {
     base_field = 555;
@@ -295,114 +292,184 @@ class MyBaseClass {
 Object.setPrototypeOf(MyBaseClass.prototype, new BaseClass({ strict: true }));
 ```
 
-### 5. ConstructorFunction Pattern
-
-```typescript
-import { define, ConstructorFunction } from 'mnemonica';
+### Topologica directory structures
 
-const MyFn = function (this: any) {
-    this.field = 123;
-} as ConstructorFunction<{ field: number }>;
+[Topologica](https://github.com/mythographica/topologica)-style directory hierarchies are scanned for handler files, and a type tree is built from the directory layout:
 
-const MyFnType = define('MyFnType', MyFn);
 ```
-
-## CLI Features
-
-### Tree Output
-
-The CLI displays type hierarchy as a tree:
-
-```bash
-$ npx tactica
-
-Type Hierarchy (Trie):
-└── UserTypeInstance
-    └── AdminTypeInstance
-        └── SuperAdminTypeInstance
-└── ProductTypeInstance
-    ├── DigitalProductTypeInstance
-    └── PhysicalProductTypeInstance
+ai-types/
+├── Sentience/
+│   ├── index.ts            // exports SentienceHandler(this, data)
+│   └── Consciousness/
+│       └── index.ts        // exports ConsciousnessHandler(this, data)
 ```
 
-### Code Coverage
+Auto-discovered directories (relative to `tsconfig.json`): `./ai-types`, `./types`, `./topologica-types`, plus the same names under `./src/`.
 
-Run tests with coverage:
+Add custom directories with `--topologica`:
 
 ```bash
-npm run test:coverage
+npx tactica --topologica ./src/ai-types,./custom/topologica
 ```
 
-## Integration with Your Workflow
-
-### .gitignore
-
-Tactica automatically adds `.tactica/` to your `.gitignore` if not already present.
-
-### IDE Support
-
-With the Language Service Plugin:
-- **VS Code**: Automatic type updates on file save
-- **WebStorm**: Works with TypeScript service
-- **Vim/Neovim**: Works with coc.nvim, nvim-lspconfig
+## Property Type Inference
+
+The analyzer infers property types from constructor bodies and class members. Supported expression patterns:
+
+| Pattern | Inferred type |
+|---|---|
+| `this.x = 'foo'` | `string` |
+| `this.x = 123` | `number` |
+| `this.x = true` | `boolean` |
+| `this.x = []` / `new Array()` | `Array<…>` |
+| `this.x = {}` | `object` |
+| `this.x = new Date()` | `Date` |
+| `this.x = new Map()` / `new Set()` | `Map<…>` / `Set<…>` |
+| `this.x = Date.now()` | `number` |
+| `this.x = parseInt(…)` / `parseFloat(…)` | `number` |
+| `this.x = String(…)` / `Number(…)` / `Boolean(…)` | `string` / `number` / `boolean` |
+| `this.x = a + b` (where `a, b: number`) | `number` |
+| `` this.x = `${a} ${b}` `` | `string` |
+| `this.x = data.field` | type of `data.field` from the parameter annotation |
+| `this.x = data.field \|\| []` | type of the fallback expression |
+| `this.x = data.field ? a : b` | type of the truthy branch |
+| `Object.assign(this, data)` | all fields of `data`'s type annotation |
+| async / sync constructor functions | same rules |
+
+When inference fails the property's type falls back to `unknown` (or `any` in some Topologica paths) — safe, and you can refine manually.
 
 ## API Reference
 
-### MnemonicaAnalyzer
+### `MnemonicaAnalyzer`
 
-```typescript
+```ts
 class MnemonicaAnalyzer {
     constructor(program?: ts.Program);
+
     analyzeFile(sourceFile: ts.SourceFile): AnalyzeResult;
     analyzeSource(sourceCode: string, fileName?: string): AnalyzeResult;
+
+    resetUsages(): void;                    // call between definition pass and usage pass
+    addTopologicaType(fullPath: string, node: TypeNode): void;
+
     getGraph(): TypeGraphImpl;
+    getDefinitions(): Map<string, DefinitionInfo>;
+    getUsages():      Map<string, UsageInfo[]>;
+    getEDSUsages():   Map<string, EDSInfo[]>;
+    getFlowUsages():  Map<string, FlowInfo[]>;
 }
 ```
 
-### TypeGraphImpl
+### `TopologicaAnalyzer`
+
+```ts
+class TopologicaAnalyzer {
+    analyzeDirectory(directoryPath: string): { types: Map<string, TypeNode>; errors: string[] };
+    getGraph(): TypeGraphImpl;
+    getErrors(): string[];
+}
+```
 
-```typescript
+### `TypeGraphImpl`
+
+```ts
 class TypeGraphImpl implements TypeGraph {
-    roots: Map<string, TypeNode>;
+    roots:    Map<string, TypeNode>;
     allTypes: Map<string, TypeNode>;
+
     addRoot(node: TypeNode): void;
     addChild(parent: TypeNode, child: TypeNode): void;
     findType(fullPath: string): TypeNode | undefined;
+    findTypeByName(name: string): TypeNode | undefined;
     getAllTypes(): TypeNode[];
+    clear(): void;
+
     *bfs(): Generator<TypeNode>;
     *dfs(node?: TypeNode): Generator<TypeNode>;
+
+    static createNode(name, parent, sourceFile, line, column): TypeNode;
 }
 ```
 
-### TypesGenerator
+### `TypesGenerator`
 
-```typescript
+```ts
 class TypesGenerator {
-    constructor(graph: TypeGraphImpl);
-    generate(): GeneratedTypes;
+    constructor(graph: TypeGraphImpl, esm?: boolean);
+
+    generateTypesFile():           GeneratedTypes; // default mode → types.ts
+    generateTypeRegistry():        GeneratedTypes; // default mode → registry.ts
+    generateGlobalAugmentation():  GeneratedTypes; // legacy mode  → index.d.ts
     generateSingleType(node: TypeNode): string;
 }
 ```
 
-### TypesWriter
+### `TypesWriter`
 
-```typescript
+```ts
 class TypesWriter {
     constructor(outputDir?: string);
-    write(generated: GeneratedTypes): string;
-    writeTo(filename: string, content: string): string;
+
+    writeTypesFile(generated: GeneratedTypes): string;          // → outputDir/types.ts
+    writeGlobalAugmentation(generated: GeneratedTypes): string; // → outputDir/index.d.ts
+    writeTo(filename: string, content: string): string;         // → outputDir/<filename>
+
+    writeDefinitionsFile(map: Map<string, DefinitionInfo>): string; // → outputDir/definitions.json
+    writeUsagesFile     (map: Map<string, UsageInfo[]>):    string; // → outputDir/usages.json
+    writeEDSFile        (map: Map<string, EDSInfo[]>):      string; // → outputDir/eds.json
+    writeFlowFile       (map: Map<string, FlowInfo[]>):     string; // → outputDir/flow.json
+
+    write(generated: GeneratedTypes): string; // legacy alias for writeTypesFile
     clean(): void;
     getOutputDir(): string;
 }
 ```
 
+### Types
+
+`TacticaConfig`, `TypeNode`, `TypeGraph`, `PropertyInfo`, `ConstructorParamInfo`, `AnalyzeResult`, `AnalyzeError`, `GeneratedTypes`, `DefinitionInfo`, `UsageInfo`, `UsagesJson`, `DefinitionsJson`, `EDSInfo`, `EDSJson`, `EDSKind`, `FlowInfo`, `FlowJson`, `FlowKind` — all exported from `@mnemonica/tactica`. See [`src/types.ts`](src/types.ts) for the full schema.
+
+## EDS (Execution Data Storage) Tracking
+
+When enabled, tactica detects execution-flow patterns alongside type definitions. Each detection emits a record into `.tactica/eds.json`.
+
+| Function | EDS kind | Description |
+|---|---|---|
+| `wrap(fn)`, `wrapArgs(fn)`, `wrapInstanceMethods(obj)` | `wrap` | Wrap a function / arguments / instance methods for context propagation |
+| `link(parent, child)`, `runWithInstance(inst, fn)` | `link` | Link two instances in the EDS chain |
+| `getLastContext()`, `getErrorInstance(err)` | `contextConsume` | Read the current / error-attached EDS context |
+| `enrichError(err, inst)` | `errorEnrich` | Attach an instance to an error |
+| `attachHooks(types)` | `hookAttach` | Install hooks on the given types |
+| `createDiveInterceptor()` | `adapterUse` | NestJS interceptor adapter |
+| `createDivePlugin()` | `adapterUse` | Fastify plugin adapter |
+| `createDiveMiddleware()` | `adapterUse` | Express middleware adapter |
+
+`eds.json` structure:
+
+```json
+{
+    "version": "1.0",
+    "generatedAt": "2026-05-22T…",
+    "eds": {
+        "UserEntity": [
+            {
+                "location": "/project/src/queue.ts:45:12",
+                "kind": "wrap",
+                "code": "wrap(process)",
+                "targetType": "UserEntity"
+            }
+        ]
+    }
+}
+```
+
 ## How It Works
 
-1. **Parse**: TypeScript AST is parsed to find `define()` and `decorate()` calls
-2. **Analyze**: The analyzer extracts type names, properties, and hierarchy
-3. **Graph**: A Trie (tree) structure represents the type hierarchy
-4. **Generate**: TypeScript declarations are generated from the graph
-5. **Output**: Files are written to `.tactica/` directory
+1. **Parse** — load `tsconfig.json`, build a `ts.Program`, walk each source file's AST.
+2. **Detect** — find `define()` and `@decorate()` calls, plus `lookupTyped` lookups, `new` expressions, and EDS / flow patterns.
+3. **Graph** — build a Trie of types in `TypeGraphImpl`, with parent links via the chain of `.define()` calls and `@decorate(Parent)` references.
+4. **Generate** — emit `types.ts`, `registry.ts`, `index.ts` (default mode) or `index.d.ts` (legacy mode), plus `definitions.json`, `usages.json`, `flow.json`, and optionally `eds.json`.
+5. **Write** — files land in the output directory (default `.tactica/`).
 
 ```
 Type Hierarchy (Trie)
@@ -416,60 +483,71 @@ Type Hierarchy (Trie)
     └── properties: { items: Item[] }
 ```
 
-## Troubleshooting
+## Known Limitations
 
-### Types not updating
+### Rest / spread parameters with tuple types
 
-1. Check that the plugin is loaded in `tsconfig.json`
-2. Restart TypeScript service (VS Code: Command Palette → "TypeScript: Restart TS Server")
-3. Verify file patterns in `include`/`exclude` config
+The analyzer cannot extract property types from rest parameters that use tuple types:
 
-### Generated types have errors
+```ts
+// ❌ Property types resolve to unknown
+export const UserEntity = define('UserEntity', function (
+    this: UserEntityInstance,
+    ...args: [{ id: string; email: string; name: string }, ...unknown[]]
+) {
+    const data = args[0];
+    Object.assign(this, data);
+});
+```
 
-1. Ensure all mnemonica types have explicit type annotations
-2. Check that `define()` calls use string literals for type names
-3. Verify property types are valid TypeScript
+**Workaround:** use a direct parameter with the same type annotation.
 
-### Plugin not working
+### Deep nested property access
 
-```bash
-# Test with CLI first
-npx tactica --verbose
+Multi-level property access in constructors falls back to `unknown`:
 
-# Check for parsing errors
-npx tactica --verbose 2>&1 | grep -i error
+```ts
+// ⚠️ this.name's inferred type is unknown
+const UserType = define('UserType', function (this: any, data: { profile: { name: string } }) {
+    this.name = data.profile.name;
+});
 ```
 
-## Related Projects
+**Workaround:** flatten the data structure or use a direct parameter.
 
-- [mnemonica](https://github.com/wentout/mnemonica) - Instance inheritance system
-- [@mnemonica/topologica](https://github.com/mythographica/topologica) - Filesystem-based type discovery
-- [typeomatica](https://github.com/wentout/typeomatica) - Runtime type checking with `@Strict` decorator and `BaseClass`
+### `exposeInstanceMethods` is not parsed
 
-## Testing
+Mnemonica accepts the `exposeInstanceMethods` option at runtime, but tactica's `extractConfig()` only parses `strictChain` and `blockErrors` from `define()` options today. The runtime behavior is unaffected.
 
-Tactica includes comprehensive test coverage:
+### Single-pass analysis without binding
 
-```bash
-# Run all tests
-npm test
+The analyzer does not use `ts.Program.getTypeChecker()` for resolution, so cross-file type references in unusual shapes may resolve to `unknown`.
+
+## Troubleshooting
+
+**Generated types are missing properties** — make sure the constructor function has either an explicit `this:` type annotation, or that the data parameter has an inline / aliased type (`{ id: string }` or `Foo` where `type Foo = { id: string }`). Property inference walks one level of indirection.
+
+**`new user.AdminType()` shows red squiggles** — confirm `.tactica/types.ts` is in your `tsconfig.json` `include`. If you use `lookupTyped`, also import `.tactica/registry.ts` somewhere.
+
+**`mnemographica` (VS Code extension) shows no graph** — confirm `.tactica/definitions.json` and `.tactica/types.ts` exist; run `npx tactica --verbose` to see what was discovered.
 
-# Run with coverage
-npm run test:coverage
+**`@mnemonica/dive` users**: EDS data should appear in `.tactica/eds.json`. If it's missing, run with `--eds --verbose` to force-enable and check the log.
+
+## Testing
+
+```bash
+npm test                  # mocha + chai, all suites
+npm run test:coverage     # nyc text report
+npm run test:coverage:html  # nyc html report
 ```
 
-Test suites include:
-- **Analyzer tests** - Core AST parsing functionality
-- **Generator tests** - TypeScript declaration generation
-- **Writer tests** - File I/O operations
-- **Integration tests** - End-to-end workflows
-- **Example tests** - Patterns from `tactica-test/` project
-- **Typeomatica tests** - Combined mnemonica + typeomatica patterns
+## Related Projects
+
+- [mnemonica](https://github.com/wentout/mnemonica) — the instance-inheritance runtime that this generator targets
+- [typeomatica](https://github.com/wentout/typeomatica) — companion runtime type guards (`@Strict`, `BaseClass`)
+- [@mnemonica/topologica](https://github.com/mythographica/topologica) — filesystem-based type discovery (consumed by tactica's `--topologica` mode)
+- [mnemographica](https://github.com/mythographica/mnemographica) — VS Code extension that consumes tactica's `.tactica/` output for IDE features
 
 ## License
 
 MIT
-
-## Contributing
-
-Contributions welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details.