@mnemonica/tactica 0.3.0 → 0.3.7

package/README.md

@@ -138,7 +138,7 @@ Tactica writes everything under the `--output` directory (default `.tactica/`):
 | `flow.json` | always | Native instance-flow patterns (property reads/writes, method calls, destructuring, returns, spreads, etc.) per type. |
 | `instrumentation.json` | always | v2 envelope. `points`: framework lifecycle crossroads (interceptors, guards, pipes, filters, middleware) detected via **plugin-supplied vocabulary** — heritage declarations, decorator sites, provider-token registrations, `consumer.apply()` wiring. Syntactic only — no dive dependency; with no plugins loaded, `points` is `[]`. `creationGraph`: the inside-out walk from every instantiation site out to the starters — see "Creation graph" below. |
 | `modules.json` | always | Module-scope graph: every module's `exportedBindings`/`importedBindings` (functions, classes, consts, types — not only mnemonica types), project-internal `dependencies`, `builtinSpecifiers` (Node builtins are skipped entirely — both `'path'` and `'node:path'` forms), `unresolvedSpecifiers`, circular-import `cycles`, and cross-module mnemonica-type `edges`. Resolution uses `ts.resolveModuleName` with the project's compilerOptions (tsconfig `paths`, extensionless imports, index files) — no type checker. Bindings resolved into `node_modules` are marked `external: true` and never enter `dependencies`. |
-| `scopes.json` | always | Local-scope graph: function/method/arrow scopes only (no block scopes) plus one module scope per file; variables with `typePath` (mnemonica type when known), `isParameter`, `isMutable`, and `reassignments` — each reassignment of a mutable binding is a flow-termination point. |
+| `scopes.json` | always | Local-scope graph: function/method/arrow scopes only (no block scopes) plus one module scope per file; variables with `typePath` (mnemonica type when known), `isParameter`, `isMutable`, and `reassignments` — each reassignment of a mutable binding is a flow-termination point. `lookup()` initializers resolve through the same tier law as the analyzer (scope-chain receiver first, then the analyzer's source-relative/root law), so scopes metadata never disagrees with the hard-fail verdicts. |
 | `eds.json` | when EDS enabled | Execution-flow patterns (`wrap`, `current`, `getFlow`, `attachHooks` lifecycle wiring). Consumed by tools that visualize execution chains. |
 
 ### Default mode (types.ts + registry.ts)
@@ -471,6 +471,131 @@ The analyzer infers property types from constructor bodies and class members. Su
 
 When inference fails the property's type falls back to `unknown` (or `any` in some Topologica paths) — safe, and you can refine manually.
 
+### Referenced types in constructor signatures
+
+A constructor parameter that references a named type (`record: SharedShape`) resolves **through the importing file's own import statements** — relative and tsconfig-paths imports are followed to the declaration (chasing re-export barrels), and imported classes/interfaces/type aliases with extractable fields are expanded inline, **inherited members included**: `extends` chains are walked (depth-bounded, cycle-guarded) and parent fields merge with the declaration's own fields overriding on name clash. A field typed by a `typeof` query over a module-level const array (`status?: typeof statusList[number]`) expands to the element literal union (`status?: 'active' | 'closed'`); any other `typeof` source degrades that field to `unknown` — a bare `typeof name` is never emitted, since the generated file has no imports to resolve it against. An import is never shadowed by a same-named declaration elsewhere in the program. A reference that resolves not at all (a ghost name, declared nowhere) emits `unknown` — generated `.tactica/types.ts` carries no import statements of its own, so a bare unresolvable name is never emitted. A reference that resolves *ambiguously* — several of your project's files declare the name and no import chooses between them — is **fatal** like the mnemonica-graph identity law below: tactica prints the reference site and every declaration site, exits non-zero, and writes no output. An import anchoring the reference is never ambiguity (the import wins, duplicate declarations or not), and package-declared same-named types never count — a user-local declaration always wins over a node_modules `.d.ts`. Two same-named interfaces in one file are legal TypeScript merging, not ambiguity (see Known Limitations for the last-wins caveat).
+
+**Ambiguous plain-TypeScript reference — fails, and how to fix it.** Two plain interfaces named `SharedShape` exist in different files, and a third file references a bare `SharedShape` with nothing anchoring it:
+
+```ts
+// a.ts                              // b.ts
+export interface SharedShape {      export interface SharedShape {
+	a: string;                       	b: number;
+}                                    }
+
+// consumer.ts — FATAL: which SharedShape?
+import { define } from 'mnemonica';
+
+export const Crate = define('Crate', function (this: Crate, data: SharedShape) {
+	this.item = data;
+});
+```
+
+```
+tactica: Ambiguous reference to type 'SharedShape': 2 declarations share the name and no import disambiguates — import the one you mean
+  at src/consumer.ts:6:67
+  at /abs/path/src/a.ts:1:1
+  at /abs/path/src/b.ts:1:1
+tactica: aborting — 1 resolution failure(s); no .tactica output written
+```
+
+Fix it by importing the declaration you mean — the file's own import wins over every other tier:
+
+```ts
+// consumer.ts — OK: the import anchors SharedShape → a.ts
+import { define } from 'mnemonica';
+import { SharedShape } from './a';
+
+export const Crate = define('Crate', function (this: Crate, data: SharedShape) {
+	this.item = data; // item: { a: string }
+});
+```
+
+Qualified references through a namespace import resolve one level per segment: `models.SharedShape` finds the declaration in the namespace import's module; multi-level paths (`holders.Inner.Crate`, `barrel.Deep.Gadget`) descend through namespace declarations, `export * as ns from '…'` barrels, and named re-exports of namespaces — each segment disambiguates, so two namespaces may declare the same name without colliding. What is *not* followed: ambient string-named modules (`declare module '…'`), default-export shapes behind a namespace segment, and type-only constructs with no extractable fields (unions of literals, mapped types) — those emit `unknown` like any other unresolvable reference.
+
+References to **mnemonica graph types** (types declared via `define()`, as opposed to plain TypeScript declarations) follow the runtime lookup law instead: the file's own value bindings and imports anchor the name first, then the defining type's own chain relative-first, then its collection's roots, then a program-wide search that must be unique. Same-namespace duplicate definitions (which the mnemonica runtime rejects with `ALREADY_DECLARED`) and graph references that stay ambiguous or unresolved are fatal: tactica prints every location, exits non-zero, and writes no `.tactica` output at all.
+
+**Ambiguous reference — fails, and how to fix it.** Two types named `Token` exist under different parents, and a third file references a bare `Token` with nothing anchoring it:
+
+```ts
+// defs.ts
+export const Holder = define('Holder', function (this: Holder) { /* … */ });
+export const Token = Holder.define('Token', function (this: Token, data: { mark: string }) { /* … */ });
+
+// other.ts
+export const Other = define('Other', function (this: Other) { /* … */ });
+Other.define('Token', function (this: Token, data: { hue: string }) { /* … */ });
+
+// consumer.ts — FATAL: which Token?
+export const Crate = define('Crate', function (this: Crate, data: Token) {
+	this.item = data;
+});
+```
+
+```
+tactica: Ambiguous reference to mnemonica type 'Token': 2 types share the name and neither the parent chain nor the imports disambiguate
+  at src/consumer.ts:7:67
+  at src/defs.ts:8:29
+  at src/other.ts:9:7
+tactica: aborting — 1 resolution failure(s); no .tactica output written
+```
+
+Fix it by anchoring the reference — either import the constructor you mean (the import wins over every other tier), or use the full generated name:
+
+```ts
+// consumer.ts — OK: the import anchors Token → Holder.Token
+import { Token } from './defs';
+export const Crate = define('Crate', function (this: Crate, data: Token) {
+	this.item = data;
+});
+
+// or — OK: fully-qualified generated type name
+export const Crate = define('Crate', function (this: Crate, data: Holder_Token) {
+	this.item = data;
+});
+```
+
+**Duplicate in one namespace — fails, and there is only one fix.** Two types with the same name under the same parent (or two same-named roots) are what the mnemonica runtime rejects with `ALREADY_DECLARED`; tactica fails the generation instead of emitting a wrong graph:
+
+```ts
+// dup-a.ts                     // dup-b.ts
+export const A = define(        export const B = define(
+	'DupRoot', …);              	'DupRoot', …);
+```
+
+```
+tactica: Duplicate definition of 'DupRoot' in one namespace — the mnemonica runtime would throw ALREADY_DECLARED
+  at src/dup-a.ts:3:22
+  at src/dup-b.ts:6:23
+tactica: aborting — 1 resolution failure(s); no .tactica output written
+```
+
+Rename one of them. Same-named types under **different** parents (`User.Address` and `Company.Address`) are legal mnemonica and never reported.
+
+**Unresolved `lookup()` path — fails, with a did-you-mean.** Literal `lookup()` paths are validated against the complete graph after analysis. A path matching no type is what the runtime answers with `undefined` — the `TypeError` arrives one line later at the `new` — so it is fatal too, and same-named types elsewhere in the graph are listed as candidates:
+
+```ts
+// consumer.ts — FATAL: no root 'Token'; Holder.Token and Other.Token exist
+const TokenCtor = lookup('Token');
+export const instance = new TokenCtor({ mark: 'x' });
+```
+
+```
+tactica: Unresolved lookup of mnemonica type 'Token': the runtime would return undefined — 2 graph type(s) carry the name off-root (Holder.Token, Other.Token); use the full dotted path
+  at src/consumer.ts:6:19
+  at src/defs.ts:8:29
+  at src/other.ts:9:7
+tactica: aborting — 1 resolution failure(s); no .tactica output written
+```
+
+```ts
+// OK: dotted absolute path, or receiver-relative resolution
+const ByPath     = lookup('Holder.Token');
+const ByReceiver = Holder.lookup('Token');
+```
+
+Non-literal lookup arguments (computed strings) stay best-effort and are not validated.
+
 ## API Reference
 
 ### `MnemonicaAnalyzer`
@@ -491,6 +616,7 @@ class MnemonicaAnalyzer {
     getEDSUsages():   Map<string, EDSInfo[]>;
     getFlowUsages():  Map<string, FlowInfo[]>;
     getInstrumentationPoints(): InstrumentationPoint[];
+    getResolutionErrors(): ResolutionError[];  // fatal duplicate/ambiguous graph + plain-TS references (hard-fail law)
 }
 ```
 
@@ -658,6 +784,7 @@ When enabled, tactica detects execution-flow patterns alongside type definitions
 - `scopeId` — the scopeId of the scope holding the wrap call site (fallback join).
 - `wrapsTypePath` — the mnemonica fullPath of the instance argument, resolved through the scope-variable chain (innermost binding wins; an untyped local shadows a typed outer one rather than being guessed).
 - `via` — the location of the enclosing wrap site when the call is nested inside another wrapped body (or returns a function): the wrappers-graph generation chain is built from it.
+- `scope` — the enclosing mnemonica type path. Lexical scoping (the owning `define()`/`lazy()` handler or `@decorate()`-ed class) wins; a wrap site outside any handler — the fire-and-forget-wrapper shape — is attributed through its instance/context argument (a tracked assignment like `const holder = new Holder(…)`, or the enclosing function's parameter annotation resolved through the graph law), and nested sites (function-valued returns, lexically nested wraps) inherit the causing wrap site's scope down the `via` chain. Sites attributable to nothing stay under the `unknown` key with `scope` absent.
 
 ## Instrumentation Points
 
@@ -681,6 +808,9 @@ interface TacticaPlugin {
     useDecorators?: Record<string, InstrumentationKind>;
     // `{ provide: TOKEN, useClass: Impl }` registrations: token identifier -> kind
     appTokens?: Record<string, InstrumentationKind>;
+    // factory calls inside listed decorators' args: factory method name ->
+    // kind + which factory-call argument holds the target class (default 0)
+    decoratorArgFactories?: Record<string, { kind: InstrumentationKind; targetArg?: number }>;
     // opt in to shape-based `consumer.apply(Mw).forRoutes(...)` detection
     middlewareWiring?: boolean;
 }
@@ -689,7 +819,8 @@ interface TacticaPlugin {
 Programmatic callers pass plugins directly: `new MnemonicaAnalyzer(program, plugins)` or `run({ …, plugins })`; config-file plugins append after programmatic ones, and later plugins override earlier ones on the same identifier key. Detection covers:
 
 - **Heritage** — `class X implements <plugin-listed interface>` (matched by interface identifier name). Bare declarations carry scope `module` (attachment statically unknown).
-- **Decorator sites** — plugin-listed decorators on classes or methods, including inline instances (`@Register(new Impl(…))`). One point per referenced class; scope is `controller:<Name>` or `method:<Class>.<method>`.
+- **Decorator sites** — plugin-listed decorators on classes, methods, or method parameters, including inline instances (`@Register(new Impl(…))`). One point per referenced class; scope is `controller:<Name>` or `method:<Class>.<method>` (parameter-decorated sites take the enclosing method's scope — the attachment is the handler, not the argument name).
+- **Decorator-arg factories** — a `CallExpression` argument of the form `<anything>.<factory>(…)` inside a listed decorator's args (class, method, or parameter position), e.g. `@UsePipes(mvp.forType(Dto))` and the parameter form `@Body(mvp.forType(Entity, Dto))`: when `<factory>` is plugin-listed, a point of the configured `kind` is emitted with the class in `targetArg` (default 0) as the target. Factory calls whose method name is not listed are ignored, as are listed factories whose configured position is not an identifier. Points resolve `location`/`code` to the target's declaration and dedupe exactly like other decorator sites.
 - **Global providers** — `{ provide: <plugin-listed token>, useClass: X }` object literals → scope `global`. `useExisting`/`useFactory` without `useClass` are skipped.
 - **Middleware wiring** — `consumer.apply(Mw).forRoutes(...)` inside a class's `configure()` method → scope `module`, targets from `forRoutes` arguments when statically readable. Requires `middlewareWiring: true` from any loaded plugin.
 
@@ -806,7 +937,21 @@ Mnemonica accepts the `exposeInstanceMethods` option at runtime, but tactica's `
 
 ### Single-pass analysis without binding
 
-The analyzer does not use `ts.Program.getTypeChecker()` for resolution, so cross-file type references in unusual shapes may resolve to `unknown`.
+The analyzer does not use `ts.Program.getTypeChecker()` for resolution. Plain TypeScript references in constructor signatures resolve through the importing file's import statements first, then its local declarations, and only then a unique same-named declaration across the scanned files — so a reference whose name is genuinely absent (or lives behind unresolvable specifiers) resolves to `unknown`, while a name several of your own files declare with no import to disambiguate fails hard (see above). References to mnemonica graph types follow the path-aware lookup law described above and fail hard instead of degrading to `unknown`.
+
+Two expansion boundaries stay name-based and deliberate: **heritage** — `extends` chains are walked through the same import-aware machinery (depth-capped, cycle-guarded), but bases that resolve to an external/node_modules declaration or to a non-identifier expression (mixin calls like `extends mixin(X)`) are not followed — their inherited fields simply stay absent, same as before the walk existed. And **`typeof` fields** — only module-level const arrays with statically visible literal elements expand to the literal union (cross-file only when the const is imported by the declaring file); every other `typeof` source degrades the field to `unknown`.
+
+### Same-file interface merging is last-wins
+
+Two same-named interfaces in ONE module are legal TypeScript declaration merging, and tactica does not treat them as ambiguity (the fatal class is same-named declarations across several files, unanchored by an import). Resolution keeps a single declaration per name per file, and it is the last one — members from earlier declarations are not combined:
+
+```ts
+// merged.ts — resolves to { b: number }; the `a: string` member is not picked up
+export interface SharedShape { a: string; }
+export interface SharedShape { b: number; }
+```
+
+**Workaround:** declare the merged shape once, or split the interfaces under distinct names and import the one you mean.
 
 ### Custom collection name conflicts
 

package/lib/analyzer.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { AnalyzeResult, DefinitionInfo, UsageInfo, EDSInfo, FlowInfo, InstrumentationPoint } from './types';
+import { AnalyzeResult, DefinitionInfo, UsageInfo, EDSInfo, FlowInfo, InstrumentationPoint, ResolutionError } from './types';
 import { TypeGraphImpl } from './graph';
 import { TacticaPlugin } from './plugins';
 /**
@@ -20,7 +20,6 @@ export declare class MnemonicaAnalyzer {
     private functionBindings;
     private nestedWrapVia;
     private wrapEntryByNode;
-    private typeAliases;
     private variableToTypeMap;
     private moduleObjectVariables;
     private createTypesCollectionVariables;
@@ -30,6 +29,27 @@ export declare class MnemonicaAnalyzer {
     private instrumentationClassDecls;
     private instrumentationSites;
     private instrumentationVocabulary;
+    private referencedTypeDecls;
+    private referencedTypeImports;
+    private referencedTypeReExports;
+    private referencedTypeExportStars;
+    private referencedTypeExportAliases;
+    private referencedTypeNamespaces;
+    private referencedTypeNamespaceStars;
+    private referencedTypeResolutionCache;
+    private referencedTypeConstArrays;
+    private referencedTypeCompilerOptions;
+    private currentReferencedTypeFile;
+    private expandingReferencedAliases;
+    private defineSites;
+    private graphReferenceErrors;
+    private lookupReferencesValidated;
+    private lookupReferences;
+    private plainTypeReferencesValidated;
+    private plainTypeReferences;
+    private fileGraphBindings;
+    private currentGraphAnchor;
+    private processedCalls;
     constructor(program?: ts.Program, plugins?: TacticaPlugin[]);
     /**
      * Reset usage-related state for a fresh pass.
@@ -93,6 +113,250 @@ export declare class MnemonicaAnalyzer {
      * createTypesCollection are recognized without relying on the type checker.
      */
     private trackImports;
+    /**
+     * Record a named referenced-type declaration (type alias, class, or
+     * interface) for the file currently being visited.
+     */
+    private trackReferencedTypeDeclaration;
+    /**
+     * Record consts initialized with an array literal (optionally wrapped in
+     * `as const` / `satisfies`), so a `typeof statusList[number]` field type
+     * expands to the element literal union — the generated file carries no
+     * imports, so emitting the bare `typeof statusList` query would be an
+     * unresolvable name downstream. First binding wins: a nested shadow
+     * must not replace the module-level const the typeof refers to.
+     */
+    private trackReferencedTypeConstArray;
+    /**
+     * Find the array literal behind a module const referenced through
+     * `typeof`: the declaring file's own consts first (the F13 case is a
+     * NON-exported const in the same module as the expanded class), then —
+     * when the file imports the name — the imported module's consts.
+     * External modules are never analyzed, so those yield nothing.
+     */
+    private findReferencedConstArray;
+    /**
+     * Element literal types of a tracked const array: every element must be
+     * a plain literal (optionally wrapped in `as const` / `satisfies`) —
+     * string, numeric, boolean, or null. Spreads, identifiers, and nested
+     * arrays mean the union is not statically visible and yield undefined,
+     * so the caller degrades the field to `unknown` rather than guessing.
+     */
+    private literalTypesOfArray;
+    /**
+     * Emit-type for `typeof name` when `name` is a tracked const array: the
+     * union of its element literal types (`'active' | 'closed'`). Every
+     * other typeof source — non-array consts, functions, classes, names not
+     * tracked at all — yields undefined, so the caller degrades the field
+     * to `unknown`: a bare `typeof name` emitted into types.ts has no
+     * import to resolve against downstream.
+     */
+    private typeOfConstArrayUnion;
+    /**
+     * Record the importing file's named/namespace/default import bindings so
+     * referenced-type names resolve through the file's own import statements
+     * (F10) rather than a program-wide name map.
+     */
+    private trackReferencedTypeImport;
+    /**
+     * Record re-export wiring (`export { X } from '…'`, `export * from '…'`,
+     * `export { X as Y }`) so resolution can chase barrels to the origin
+     * module. Mirrors ModuleGraphBuilder.resolveOrigin, name-based only.
+     */
+    private trackReferencedTypeReExport;
+    /**
+     * Resolve a module specifier from a containing file with the program's
+     * compilerOptions (tsconfig `paths`, extensionless imports, index files).
+     * Module resolution only — the no-getTypeChecker() precedent stays.
+     */
+    private resolveReferencedTypeModule;
+    /**
+     * Look up a name in one resolved module, chasing re-export barrels with a
+     * bounded depth. External (node_modules) modules hold no in-project
+     * declarations and stop the chase.
+     */
+    private findReferencedTypeInModule;
+    /**
+     * Resolve a referenced type name as used in fromFile, import-aware:
+     *   1. the file's own import statements (relative + tsconfig paths,
+     *      chased through re-export barrels),
+     *   2. the file's local declarations,
+     *   3. the unique same-named declaration across scanned files.
+     * Returns undefined when nothing matches (or the match is ambiguous),
+     * in which case the caller falls back to `unknown`.
+     */
+    private resolveReferencedTypeDeclaration;
+    /**
+     * External/ambient declaration files (.d.ts, anything under
+     * node_modules) never participate in plain-TS referenced-type
+     * resolution or the ambiguity law: they are not project source, the
+     * CLI never analyzes them, and a user-local declaration always wins
+     * over a package-declared same-named type.
+     */
+    private isExternalDeclFile;
+    /**
+     * Properties of a referenced class/interface/alias-of-literal declaration,
+     * shared by `this:`-parameter expansion and inline type emission.
+     * Inherited members are included: the extends chain is walked
+     * (depth-capped, cycle-guarded) and parent fields merge first, the
+     * declaration's own fields overriding on name clash.
+     */
+    private referencedDeclarationProperties;
+    private referencedDeclarationPropertiesInner;
+    /**
+     * Property signatures of interface/alias type-literal members, into
+     * the given map.
+     */
+    private collectTypeElementProperties;
+    /**
+     * Resolve the heritage clause of a class (`extends Base`) or interface
+     * (`extends A, B`) to referenced-type declarations through the SAME
+     * import-aware machinery as plain references (the declaring file's own
+     * imports first, then its locals, then the unique program-wide
+     * declaration). Unresolvable or external bases yield nothing — their
+     * inherited fields simply stay absent, same as before this walk
+     * existed. Mixin calls (`extends mixin(X)`) and namespace access are
+     * not followed.
+     */
+    private resolveHeritageDeclarations;
+    /**
+     * Expand a referenced-type declaration to a self-contained type string
+     * for emission into generated files: type aliases through inferType,
+     * classes and interfaces through their (public, non-method) fields.
+     * Nested references resolve against the declaring file while expanding.
+     */
+    private expandReferencedTypeDeclaration;
+    private expandReferencedTypeDeclarationInner;
+    /**
+     * Resolve a simple (non-qualified) type reference: import-aware
+     * declaration expansion first, then the InstanceType<typeof X> pattern,
+     * then mnemonica graph types; known globals keep their bare name and
+     * anything else falls back to `unknown` so generated files never carry
+     * an unresolvable bare name. Returns undefined when the caller should
+     * keep the generic spelling (handled separately).
+     */
+    private resolveSimpleTypeReference;
+    /**
+     * Resolve a qualified type reference (models.Inner.Crate) through the
+     * current file's namespace imports. The chain's head must be a namespace
+     * import; middle segments descend through namespace declarations, named
+     * re-exports of namespaces, and `export * as ns from '…'` barrels (each
+     * segment consumed exactly once, so the walk cannot cycle); the final
+     * segment resolves to a declaration which is expanded inline. When the
+     * precise walk finds nothing, the legacy rightmost-name lookup in the
+     * head module keeps one-level forms (models.Type) working — nested
+     * declarations are recorded by plain name there too. Returns undefined
+     * when the head is not a namespace import or nothing resolves.
+     */
+    private inferQualifiedTypeReference;
+    /**
+     * Find a namespace declaration by name directly inside a module block.
+     */
+    private findNamespaceInBlock;
+    /**
+     * Find a named type declaration (alias, class, interface) directly inside
+     * a namespace block — the final segment of a descended qualified chain.
+     */
+    private findReferencedTypeInBlock;
+    /**
+     * Fallback for a type-reference name that resolves to no declaration and
+     * no graph type: known globals keep their bare name (they resolve without
+     * an import); everything else becomes `unknown` so generated types.ts
+     * never carries an unresolvable bare name (README's documented behavior)
+     * and the site is recorded for the plain-TS ambiguity validation.
+     */
+    private unresolvedTypeReferenceFallback;
+    /**
+     * Record one define()/lazy()/@decorate() site under its runtime
+     * namespace key. Two sites in one namespace are a same-namespace
+     * duplicate (the runtime throws ALREADY_DECLARED); every site is kept
+     * so the failure can report all locations.
+     */
+    private recordDefineSite;
+    /**
+     * Fatal resolution failures (hard-fail law): same-namespace duplicate
+     * mnemonica definitions plus ambiguous/unresolved mnemonica-graph
+     * references. The CLI prints every location and writes no output.
+     */
+    getResolutionErrors(): ResolutionError[];
+    /**
+     * Resolve a reference to a mnemonica graph type name, import-aware and
+     * path-aware (the hard-fail identity law, mirroring the runtime):
+     *   1. value scope — a tracked top-level binding in the referencing file
+     *      (`const Address = User.define('Address', …)`),
+     *   2. import scope — a binding exported from a module this file imports
+     *      (barrels chased),
+     *   3. nearest-chain — the anchor type's own subtypes first, then each
+     *      ancestor level (relative-first),
+     *   4. root — roots of the anchor's collection,
+     *   5. program-wide — only when exactly one type carries the name.
+     * Ambiguity (several candidates and nothing disambiguates) and absence
+     * are both returned as such — the caller records a hard failure; a bare
+     * first-match name is never emitted.
+     */
+    private resolveGraphTypeName;
+    /**
+     * Find a graph constructor binding exported by a resolved module,
+     * chasing re-export barrels with a bounded depth.
+     */
+    private findGraphBindingInModule;
+    /**
+     * Validate literal lookup() paths recorded during the usages pass
+     * against the complete graph. A lookup path matching no type is what the
+     * runtime answers with `undefined` — the TypeError arrives one line
+     * later at the `new` — so it joins the hard-fail law. The relative-first
+     * step already ran inside resolveLookupPath; whatever was recorded is
+     * the root-resolution result, so a plain findType check is the exact
+     * runtime law. Same-named types elsewhere in the graph are listed as
+     * did-you-mean candidates. Runs once per usages pass (re-armed by
+     * resetUsages); non-literal lookup arguments are never recorded and
+     * stay best-effort.
+     */
+    private validateLookupReferences;
+    /**
+     * Record a plain-TS type reference site that resolved to nothing and
+     * fell back to `unknown`, for the lazily-run ambiguity validation.
+     * Deduped by (name, location): inferType can visit the same node more
+     * than once per pass (constructor params + property inference).
+     */
+    private recordPlainTypeReferenceSite;
+    /**
+     * Project-source declaration files carrying `name` — one entry per
+     * file, so same-file interface merging counts once (not ambiguous).
+     * External/ambient declarations (.d.ts, anything under node_modules)
+     * never count: a user-local declaration always wins over a package-
+     * declared same-named type, so an external collision stays soft.
+     */
+    private plainTypeDeclarationFiles;
+    /**
+     * Validate plain-TS type reference sites recorded during the usages
+     * pass against the complete declaration map. A name declared in
+     * several project-source files — with no import in the referencing
+     * file to anchor it — is ambiguous: silently emitting `unknown` would
+     * hide a real type the author meant, so it joins the hard-fail law
+     * (the plain-TS tier of the same identity law as graph references).
+     * Absence (ghost names) and external collisions stay soft `unknown`.
+     * Runs once per usages pass (re-armed by resetUsages), mirroring
+     * validateLookupReferences: recording happens on every pass, but only
+     * the usages pass sees the complete declaration map.
+     */
+    private validatePlainTypeReferences;
+    /**
+     * `file:line:column` of a recorded declaration, for the ambiguity
+     * report. Nodes recorded during traversal keep their positions; a
+     * synthetic/unpositioned node falls back to the file itself.
+     */
+    private plainDeclLocation;
+    /**
+     * Record a hard-fail graph reference error with the reference site and
+     * every candidate location.
+     */
+    private recordGraphReferenceError;
+    /**
+     * Location (`file:line:column`) of an AST node, derived without parent
+     * pointers when necessary.
+     */
+    private nodeLocation;
     /**
      * Track aliases of the mnemonica module object, e.g.:
      *   const m = mnemonica;
@@ -203,6 +467,12 @@ export declare class MnemonicaAnalyzer {
         * For chained calls like const X = define('A').define('B'), we map X -> A (the root type)
         */
     private trackVariableAssignment;
+    /**
+     * Mirror a variable -> mnemonica fullPath binding into the per-file
+     * value-scope map (graph identity law: `typeof X` and bare references
+     * resolve through the file's own bindings first).
+     */
+    private trackFileGraphBinding;
     /**
         * Track variable assignments from lookup() calls
         * e.g., const SentienceConstructor = lookup('Sentience') maps "SentienceConstructor" -> "Sentience"
@@ -255,6 +525,15 @@ export declare class MnemonicaAnalyzer {
      *   collection.lookup('User.Admin')
      */
     private resolveLookupPath;
+    /**
+     * Lookup-law delegate for the local-scope walker (scopes.json typePath
+     * metadata): resolve a lookup() initializer call through exactly the
+     * tiers the usages pass resolved it against (same source resolution,
+     * same complete graph). The walker runs its own scope-chain value-scope
+     * tier before delegating; everything above value scope lands here, so
+     * scopes.json never disagrees with the hard-fail-law verdicts.
+     */
+    resolveLookupCallPath(call: ts.CallExpression): string | undefined;
     /**
         * Find a parent type by its name, searching in the graph.
         * When collectionId is provided, only types from that collection are considered.
@@ -338,10 +617,6 @@ export declare class MnemonicaAnalyzer {
         * Infer return type by analyzing return statements in the method body
         */
     private inferReturnTypeFromBody;
-    /**
-        * Get full text from a qualified name (e.g., Namespace.Type)
-        */
-    private getQualifiedNameText;
     /**
      * Infer type from initializer
      */
@@ -373,6 +648,24 @@ export declare class MnemonicaAnalyzer {
      * returns undefined for calls outside any type scope (module top level).
      */
     private resolveEDSScope;
+    /**
+     * Resolve a wrap site's instance/context argument to a mnemonica type
+     * path — the fire-and-forget-wrapper attribution fallback when the call
+     * sits outside any define()/lazy() handler: a tracked assignment
+     * (`const holder = new Holder(...)`), else the root identifier's
+     * (property-access roots included) parameter annotation resolved
+     * through the graph law. Ambiguity or absence stays silent — this is a
+     * metadata heuristic, not the identity-law surface.
+     */
+    private resolveWrapInstanceTypePath;
+    /**
+     * Resolve a bare-identifier type annotation of the nearest enclosing
+     * function's parameter through the mnemonica-graph tiers (value scope,
+     * imports, roots, program-wide-unique). Non-identifier and generic
+     * annotations are not graph references; ambiguity and absence yield
+     * undefined.
+     */
+    private resolveParameterAnnotationTypePath;
     /**
      * Resolve a wrap() argument to its function node without the type
      * checker: direct function expressions/arrows, or same-file bindings
@@ -397,6 +690,8 @@ export declare class MnemonicaAnalyzer {
      * site (`via` = the site whose wrapping caused it) and recurse into
      * its own returns. Returns through identifiers resolve through the
      * same-file bindings table; unresolvable returns are simply skipped.
+     * A return declared outside any type scope inherits the causing wrap
+     * site's scope attribution (the generation chain is the only holder).
      */
     private recordWrappedReturn;
     /**