@mnemonica/tactica 0.3.10 → 0.3.12

package/README.md

@@ -490,6 +490,8 @@ The analyzer infers property types from constructor bodies and class members. Su
 
 An existing annotation always beats a weaker inference: `unknown` (and `unknown`-bearing guesses like `Array<unknown>`) never overwrites a known type — `Record<string, unknown>` IS a known type — and an overwrite never drops an optionality modifier.
 
+**Method/member return annotations** follow an emission law (0.2.0 behavior, restored after the F10 bare-name ban overshot): an annotation — or any type argument inside it — that resolves to a mnemonica graph type emits the generated alias (`SomeEntry[]` → `Array<EDSRoot_SomeEntry>`; generated-alias spellings resolve via the underscore→dotted law). `InstanceType<typeof X>` — directly or through a local alias (`XInstance = InstanceType<typeof X>`) — drops the wrapper and emits the generated alias (`Definitions_DefinitionEntry`), since the alias already IS the instance type; when X does not resolve to a graph type the WHOLE expression degrades to `unknown` — `InstanceType<unknown>` is invalid TypeScript (TS2344) and is never emitted. An outer generic that is a non-graph **ambient/lib** construct (`MapIterator`, lib helpers — not declared in any analyzed project file) is emitted **verbatim** with inner graph aliases resolved, since it needs no import in the generated file. A **project-local** non-graph name stays `unknown` — the self-contained `types.ts` can carry neither the bare name nor an import (ambiguity between same-named project declarations is the fatal class, as elsewhere). This law covers method/member return annotations; constructor-signature parameters keep their accepted mirror policy.
+
 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
@@ -805,7 +807,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(…)`, the enclosing function's parameter annotation resolved through the graph law, or a `let`/`var`/`const` declaration with an EXPLICIT type annotation like `let updateCommitted: LedgerUpdate;` — declaration-site typing only, no flow analysis), and nested sites (function-valued returns, lexically nested wraps) inherit the causing wrap site's scope down the `via` chain. An UNANNOTATED `let`/`var` still buckets under `unknown` (the analyzer does not track assignments flow-sensitively) — a `const` with an analyzable initializer stays the recommended discipline. Sites attributable to nothing stay under the `unknown` key with `scope` absent.
+- `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(…)`, the enclosing function's parameter annotation resolved through the graph law, or a `let`/`var`/`const` declaration with an EXPLICIT type annotation like `let updateCommitted: LedgerUpdate;` — declaration-site typing only, no flow analysis; the annotation may be the type name or the generated nested-type alias (`UpdatePay_SomeTerminal`, mapped by the underscore→dotted naming law)); the wrap CALLEE identifier also follows a `let`/`var` binding to its first statically-visible in-scope assignment — the catch-guard pattern (`let fn; try { fn = new T(…) } catch { return } wrap(fn, …)`) attributes as `T`, while closure-only assignments and never-assigned bindings stay `unknown` (function/class boundaries are not crossed). One discipline covers both wrap arguments: assignment evidence beats an explicit annotation claim (`let fn: T`, or a wrapper arriving as an annotated parameter) beats `unknown` — the annotation pins the type only when the assignment is not resolvable (a userland call return, say). Nested sites (function-valued returns, lexically nested wraps) inherit the causing wrap site's scope down the `via` chain. An UNANNOTATED `let`/`var` still buckets under `unknown` (the analyzer does not track assignments flow-sensitively) — a `const` with an analyzable initializer stays the recommended discipline. Sites attributable to nothing stay under the `unknown` key with `scope` absent.
 
 ## Instrumentation Points
 
@@ -960,7 +962,7 @@ Mnemonica accepts the `exposeInstanceMethods` option at runtime, but tactica's `
 
 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, with the index suffix consumed entirely (`typeof statusList[number]` emits exactly `'active' | 'not_active' | 'hold'`, never `'hold'[number]`). The value-level twin — element access over a const-asserted literal array (`(<const>[…])[0]`, `([…] as const)[1]`, tracked `x[0]`) — infers the element literal under the same rules; non-numeric, out-of-range, spread, or non-literal elements and general `<T>` assertions (as opposed to `<const>`) stay `unknown`. Any assertion spelling is tracked (`[…] as const`, `satisfies`, `<const>[…]`), and signed numeric literals keep their sign (`-1 | 1`). Cross-file only when the const is imported by the declaring file. Every other `typeof` source — and any indexed-access target that fails to resolve — degrades the whole expression to `unknown`: an index suffix glued onto a fallback type (`unknown[number]`) is invalid TypeScript and is never emitted.
+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, with the index suffix consumed entirely (`typeof statusList[number]` emits exactly `'active' | 'not_active' | 'hold'`, never `'hold'[number]`). The value-level twin — element access over a const-asserted literal array (`(<const>[…])[0]`, `([…] as const)[1]`, tracked `x[0]`) — infers the element literal under the same rules; non-numeric, out-of-range, spread, or non-literal elements and general `<T>` assertions (as opposed to `<const>`) stay `unknown`. Any assertion spelling is tracked (`[…] as const`, `satisfies`, `<const>[…]`), and signed numeric literals keep their sign (`-1 | 1`). Cross-file only when the const is imported by the declaring file. Every other `typeof` source — and any indexed-access target that fails to resolve — degrades the whole expression to `unknown`: an index suffix glued onto a fallback type (`unknown[number]`) is invalid TypeScript and is never emitted. A sibling emission law governs method/member return annotations (0.2.0 behavior restored after the F10 bare-name ban overshot): inner type arguments resolving to graph types emit the generated aliases; `InstanceType<typeof X>` (directly or via a local alias) drops the wrapper and emits the alias — X unresolvable degrades the WHOLE expression to `unknown`, never `InstanceType<unknown>` (invalid TS, TS2344); a non-graph **ambient/lib** outer generic (`MapIterator`, lib helpers — not declared in any analyzed project file) emits verbatim with inner aliases resolved; a **project-local** non-graph name stays `unknown` (no imports in the generated file; same-named ambiguity is the fatal class). Constructor-signature parameters keep their accepted mirror policy and are not covered.
 
 ### Same-file interface merging is last-wins
 

package/docs/lookup-pattern.md

@@ -0,0 +1,109 @@
+# Consuming tactica Output: The lookup Pattern
+
+> **For application developers using tactica-generated types.**
+> If you generated `.tactica/types.ts` and `.tactica/registry.ts` but still write `as unknown as` casts, read this.
+
+---
+
+## The Mistake Everyone Makes
+
+You run tactica. It generates the files. You import the types. You still cast.
+
+```typescript
+// ❌ WRONG — you generated the types but didn't use them properly
+import { RequestData } from './collections/requestTypes.js';
+import type { RequestData as RequestDataT } from '../../.tactica/types.js';
+
+const requestData = new RequestData({ ... }) as unknown as RequestDataT;
+```
+
+This is the most common failure mode. The types exist. The registry exists. But you're bridging them with a cast instead of using `lookup`.
+
+---
+
+## The Correct Way
+
+```typescript
+// ✅ CORRECT — lookup uses the TypeRegistry augmentation
+import { lookup } from 'mnemonica';
+
+const RequestData = lookup('RequestData');
+const requestData = new RequestData({ ... });
+const routeData = new requestData.RouteData({ ... });
+```
+
+`lookup('RequestData')` returns the constructor **typed through the registry**. TypeScript knows:
+- The constructor signature
+- The instance properties
+- That the instance has `.RouteData`, `.PageData`, etc.
+
+No cast needed. The registry does the work.
+
+---
+
+## Why Importing the Type Is Not Enough
+
+`tactica` generates two files:
+
+1. `.tactica/types.ts` — exports like `export type RequestData = {...}`
+2. `.tactica/registry.ts` — augments `mnemonica.TypeRegistry`
+
+Importing from `types.ts` gives you the **instance shape**. It does NOT give you the **constructor type** with sub-constructors.
+
+The registry augmentation is what teaches TypeScript that `lookup('RequestData')` returns a constructor whose instances have `.RouteData`. Without `lookup`, you're just importing shapes and casting between them.
+
+---
+
+## Module-Level Usage
+
+`lookup` is a runtime lookup, but it's safe to call at module level:
+
+```typescript
+// ✅ Safe and correct
+const RequestData = lookup('RequestData');
+const EngineRequest = lookup('EngineRequest');
+
+app.get('/', async () => {
+	const requestData = new RequestData({ ... });
+});
+```
+
+The returned constructor is the same object every time. There is no per-request overhead.
+
+---
+
+## For Decoration (Fastify, Express, etc.)
+
+Use the same `lookup` result for decoration:
+
+```typescript
+const RequestData = lookup('RequestData');
+
+app.decorate('RequestData', RequestData);
+
+// Later in a route handler:
+const requestData = new RequestData({ ... });
+```
+
+No need to import the raw constructor separately. `lookup` gives you the runtime object AND the type.
+
+---
+
+## Checklist
+
+After running `tactica`:
+
+- [ ] `.tactica/` directory exists with `types.ts` and `registry.ts`
+- [ ] `tsconfig.json` includes `.tactica/**/*` in `include`
+- [ ] You use `lookup('TypeName')` instead of direct imports
+- [ ] You do NOT write `as unknown as` with mnemonica types
+- [ ] You run `tsc --noEmit` to verify types resolve
+
+If any box is unchecked, the integration is incomplete.
+
+---
+
+## See Also
+
+- **Canonical typing guide:** [`core/docs/typed-lookup.md`](https://github.com/wentout/mnemonica/blob/master/docs/typed-lookup.md) — builder mode, the one-line `RegistryOf` bridge, and the augmented mode this repo generates for
+- **Library landing:** [`core/README.md`](https://github.com/wentout/mnemonica) — the thesis, the four data mistakes, the three type-system paths

package/lib/analyzer.d.ts

@@ -725,6 +725,40 @@ export declare class MnemonicaAnalyzer {
      * Resolve type from EDS call argument (best effort)
      */
     private resolveEDSArgumentType;
+    /**
+     * let-in-try: find the RIGHT-HAND SIDE of the first statically-visible
+     * assignment to `name` in the scope that declares it. The declaring
+     * container is found innermost-out (blocks, case clauses, the source
+     * file — the F20 walk); the scan recurses into nested blocks (try/
+     * catch/finally, if/else, loops, switch cases) but NEVER crosses
+     * function or class boundaries — an assignment inside a closure does
+     * not attribute. Returns undefined when the binding is declared but
+     * never assigned in scope (and stops there: an inner declaration
+     * shadows any outer binding).
+     */
+    private followScopeAssignment;
+    /**
+     * True when the statement list contains a `let`/`var`/`const`
+     * declaration for `name` (any initializer form).
+     */
+    private statementsDeclareVariable;
+    /**
+     * First `name = rhs` assignment in the statement list, recursing
+     * into nested in-scope blocks. Function and class bodies are
+     * boundaries and are not entered.
+     */
+    private findAssignmentRhsInStatements;
+    /**
+     * `name = rhs` as a direct expression statement.
+     */
+    private directAssignmentRhs;
+    /**
+     * Statement lists of the nested blocks that stay INSIDE the current
+     * scope — try/catch/finally, if/else, loops, switch cases, nested
+     * blocks, labeled statements. Function-like and class bodies are
+     * scope boundaries and yield nothing.
+     */
+    private nestedScopeBlocks;
     /**
      * Resolve the enclosing mnemonica scope of an EDS call site by walking
      * up the parent chain: nearest define()/lazy() call whose handler holds
@@ -742,6 +776,25 @@ export declare class MnemonicaAnalyzer {
      * metadata heuristic, not the identity-law surface.
      */
     private resolveWrapInstanceTypePath;
+    /**
+     * Emission-law helper (0.2.0 restoration): is `name` declared in any
+     * ANALYZED PROJECT file? External/ambient files (.d.ts, node_modules)
+     * do not count. A name with no project declaration is an ambient/lib
+     * construct — safe to emit verbatim into the self-contained types.ts;
+     * a project-local name is not (no imports in the generated file).
+     */
+    private isProjectDeclaredTypeName;
+    /**
+     * F24: resolve a bare-identifier annotation to a graph fullPath. The
+     * annotation may name the type directly (`LedgerUpdate`) or carry
+     * the GENERATED instance alias of a nested type
+     * (`UpdatePay_SomeTerminal`, imported from the generated types file
+     * via tsconfig paths) — not a graph node NAME. The name is tried
+     * as-is first, then its underscore→dotted form (the generated alias
+     * naming law; the same mapping scopes.json uses for annotations).
+     * Ambiguity and absence yield undefined.
+     */
+    private resolveAnnotationTypePath;
     /**
      * Resolve a bare-identifier type annotation of the nearest enclosing
      * function's parameter through the mnemonica-graph tiers (value scope,