agency-lang 0.2.0 → 0.4.0

package/dist/lib/cli/literate.test.js

@@ -0,0 +1,229 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { generateLiterate } from "./literate.js";
+import * as fs from "fs";
+import * as path from "path";
+const tmpDir = path.join(process.env.TMPDIR || "/tmp", "agency-literate-test");
+beforeEach(() => {
+    fs.mkdirSync(tmpDir, { recursive: true });
+});
+afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+function writeInput(name, contents) {
+    const inputDir = path.join(tmpDir, "in");
+    fs.mkdirSync(inputDir, { recursive: true });
+    const inputPath = path.join(inputDir, name);
+    fs.writeFileSync(inputPath, contents);
+    return inputPath;
+}
+function weaveAndRead(name, contents, opts = {}) {
+    const inputPath = writeInput(name, contents);
+    const outputDir = path.join(tmpDir, "out");
+    generateLiterate({}, inputPath, outputDir, [], opts.lang ?? "agency");
+    const outName = name.replace(/\.agency$/, ".md");
+    return fs.readFileSync(path.join(outputDir, outName), "utf-8");
+}
+describe("generateLiterate (weave)", () => {
+    it("turns a block comment into prose and code into a fence", () => {
+        const md = weaveAndRead("test.agency", `/* hello */
+
+def foo(): number {
+  return 1
+}
+`);
+        // prose is plain text
+        expect(md).toContain("hello");
+        // code goes in an agency fence
+        expect(md).toContain("```agency");
+        expect(md).toContain("def foo");
+        // prose appears BEFORE the fence (positional check)
+        const proseIdx = md.indexOf("hello");
+        const fenceIdx = md.indexOf("```agency");
+        expect(proseIdx).toBeGreaterThanOrEqual(0);
+        expect(fenceIdx).toBeGreaterThan(proseIdx);
+        // and "hello" must not be inside the fence
+        const fenceEndIdx = md.indexOf("```", fenceIdx + 3);
+        expect(md.substring(fenceIdx, fenceEndIdx)).not.toContain("hello");
+    });
+    it("turns a doc comment (/** */) into prose, not into a fence", () => {
+        const md = weaveAndRead("test.agency", `/** docs */
+
+def foo(): number {
+  return 1
+}
+`);
+        // The "docs" string must appear outside any fence.
+        const fenceIdx = md.indexOf("```agency");
+        expect(fenceIdx).toBeGreaterThan(0);
+        const fenceEndIdx = md.indexOf("```", fenceIdx + 3);
+        const fenceContent = md.substring(fenceIdx, fenceEndIdx + 3);
+        expect(fenceContent).not.toContain("docs");
+        // And it must appear before the fence as prose.
+        const docsIdx = md.indexOf("docs");
+        expect(docsIdx).toBeGreaterThanOrEqual(0);
+        expect(docsIdx).toBeLessThan(fenceIdx);
+    });
+    it("module-level doc comment appears once as the first prose paragraph", () => {
+        const md = weaveAndRead("test.agency", `/** module docs */
+
+def foo(): number {
+  return 1
+}
+`);
+        // Exactly one occurrence (regression guard against double-emitting from
+        // program.docComment AND the multiLineComment node).
+        const occurrences = md.split("module docs").length - 1;
+        expect(occurrences).toBe(1);
+        // And it must be the first thing in the output (no fence before it).
+        const firstFenceIdx = md.indexOf("```");
+        const docsIdx = md.indexOf("module docs");
+        expect(docsIdx).toBeGreaterThanOrEqual(0);
+        expect(docsIdx).toBeLessThan(firstFenceIdx);
+    });
+    it("line comments stay inside the code fence", () => {
+        const md = weaveAndRead("test.agency", `def foo(): number {
+  // inline comment here
+  return 1
+}
+`);
+        const fenceIdx = md.indexOf("```agency");
+        const fenceEndIdx = md.indexOf("```", fenceIdx + 3);
+        const fenceContent = md.substring(fenceIdx, fenceEndIdx + 3);
+        expect(fenceContent).toContain("// inline comment here");
+    });
+    it("adjacent block comments merge with a paragraph break", () => {
+        const md = weaveAndRead("test.agency", `/* a */
+
+/* b */
+`);
+        // No fence at all — only prose.
+        expect(md).not.toContain("```");
+        // The two prose chunks are joined by "\n\n".
+        const aIdx = md.indexOf("a");
+        const bIdx = md.indexOf("b");
+        expect(aIdx).toBeGreaterThanOrEqual(0);
+        expect(bIdx).toBeGreaterThan(aIdx);
+        expect(md.substring(aIdx, bIdx + 1)).toContain("\n\n");
+    });
+    it("--lang flag flows through to the fence language tag", () => {
+        const md = weaveAndRead("test.agency", `def foo(): number { return 1 }
+`, { lang: "typescript" });
+        expect(md).toContain("```typescript");
+        expect(md).not.toContain("```agency");
+    });
+    it("mirrors the tree for directory input", () => {
+        const inputDir = path.join(tmpDir, "src");
+        const nestedDir = path.join(inputDir, "nested");
+        fs.mkdirSync(nestedDir, { recursive: true });
+        fs.writeFileSync(path.join(inputDir, "a.agency"), `def a(): number { return 1 }\n`);
+        fs.writeFileSync(path.join(nestedDir, "b.agency"), `def b(): number { return 2 }\n`);
+        const outputDir = path.join(tmpDir, "out");
+        generateLiterate({}, inputDir, outputDir, [], "agency");
+        expect(fs.existsSync(path.join(outputDir, "a.md"))).toBe(true);
+        expect(fs.existsSync(path.join(outputDir, "nested", "b.md"))).toBe(true);
+    });
+    it("produces an empty .md for an empty input file", () => {
+        const md = weaveAndRead("empty.agency", "");
+        expect(md).toBe("");
+    });
+    it("escalates the fence delimiter when the code contains triple backticks", () => {
+        // Block comment containing ``` ends up as prose, not code — so to
+        // exercise escalation through codeFence we need backticks inside a
+        // CODE node. A doc-string is the simplest way to get a string with
+        // backticks into the code segment.
+        const md = weaveAndRead("test.agency", "def foo(): string {\n" +
+            '  """contains ``` triple backticks"""\n' +
+            '  return "x"\n' +
+            "}\n");
+        // The surrounding fence must be at least 4 backticks so the inner
+        // ``` doesn't terminate it prematurely.
+        expect(md).toMatch(/^````+agency\n/m);
+        expect(md).toMatch(/\n````+\n?$/);
+    });
+    it("escalates the fence delimiter to 5 backticks when content has 4", () => {
+        const md = weaveAndRead("test.agency", "def foo(): string {\n" +
+            '  """contains ```` four backticks"""\n' +
+            '  return "x"\n' +
+            "}\n");
+        expect(md).toMatch(/^`````+agency\n/m);
+    });
+    it("strips JSDoc-style leading `*` from multi-line block comments", () => {
+        const md = weaveAndRead("test.agency", `/**
+ * Line one
+ *
+ * Line two
+ */
+
+def foo(): number { return 1 }
+`);
+        // The leading " * " on each line is gone; paragraphs are preserved.
+        expect(md).toContain("Line one");
+        expect(md).toContain("Line two");
+        expect(md).not.toMatch(/^\s*\*\s+Line/m);
+        // The two paragraphs are separated by a blank line.
+        const oneIdx = md.indexOf("Line one");
+        const twoIdx = md.indexOf("Line two");
+        expect(md.substring(oneIdx, twoIdx)).toContain("\n\n");
+    });
+    it("preserves markdown bullets (leading `*` after the JSDoc decoration)", () => {
+        const md = weaveAndRead("test.agency", `/**
+ * Items:
+ * * one
+ * * two
+ */
+`);
+        // After stripping the JSDoc decoration, the inner "* one" / "* two"
+        // markdown bullets remain.
+        expect(md).toContain("Items:");
+        expect(md).toContain("* one");
+        expect(md).toContain("* two");
+    });
+    it("leaves single-line block comments alone", () => {
+        const md = weaveAndRead("test.agency", `/* a * b */\n`);
+        // The internal "*" is untouched.
+        expect(md).toContain("a * b");
+    });
+    it("preserves source order of imports (no hoisting, no alphabetical sort)", () => {
+        const md = weaveAndRead("test.agency", `import { zebra } from "z"
+import { apple } from "a"
+
+def hello(): string {
+  return "world"
+}
+`);
+        // Without preserveOrder, AgencyGenerator would alphabetize these
+        // imports — "apple" would come before "zebra". Pin source order.
+        const zebraIdx = md.indexOf("zebra");
+        const appleIdx = md.indexOf("apple");
+        expect(zebraIdx).toBeGreaterThan(0);
+        expect(appleIdx).toBeGreaterThan(0);
+        expect(zebraIdx).toBeLessThan(appleIdx);
+    });
+    it("preserves imports placed mid-file (no hoisting)", () => {
+        const md = weaveAndRead("test.agency", `def first(): number { return 1 }
+
+import { later } from "wherever"
+
+def second(): number { return 2 }
+`);
+        // The mid-file import must appear AFTER first() and BEFORE second().
+        const firstIdx = md.indexOf("def first");
+        const importIdx = md.indexOf("import { later }");
+        const secondIdx = md.indexOf("def second");
+        expect(firstIdx).toBeGreaterThanOrEqual(0);
+        expect(importIdx).toBeGreaterThan(firstIdx);
+        expect(secondIdx).toBeGreaterThan(importIdx);
+    });
+    it("smoke-tests against stdlib/markdown.agency (real-world AST)", () => {
+        const repoRoot = path.resolve(__dirname, "..", "..");
+        const input = path.join(repoRoot, "stdlib", "markdown.agency");
+        // Sanity: only run if the fixture exists in this checkout.
+        if (!fs.existsSync(input))
+            return;
+        const outputDir = path.join(tmpDir, "out");
+        generateLiterate({}, input, outputDir, [], "agency");
+        const md = fs.readFileSync(path.join(outputDir, "markdown.md"), "utf-8");
+        expect(md.length).toBeGreaterThan(0);
+        expect(md).toContain("```agency");
+    });
+});

package/dist/lib/cli/optimize.js

@@ -87,7 +87,17 @@ export async function optimize(config, target, opts = {}, io) {
     if (nonPromptKeys.length > 0) {
         console.warn(`Warning: @optimize(${nonPromptKeys.join(", ")}) — only prompt optimization is supported in v1. Parameter tuning for ${nonPromptKeys.join(", ")} will be ignored.`);
     }
-    const goal = goalTag.arguments[0];
+    const goalArg = goalTag.arguments[0];
+    if (!goalArg ||
+        goalArg.type !== "string" ||
+        goalArg.segments.length !== 1 ||
+        goalArg.segments[0].type !== "text") {
+        const where = goalArg?.loc
+            ? ` (line ${goalArg.loc.line}, col ${goalArg.loc.col})`
+            : "";
+        throw new Error(`@goal(...) requires a single plain string-literal argument${where}; got ${goalArg ? goalArg.type : "no argument"}.`);
+    }
+    const goal = goalArg.segments[0].value;
     console.log(`Goal: ${goal}`);
     console.log(`Running up to ${options.iterations} iterations...\n`);
     const targetNode = program.nodes.find((n) => n.type === "graphNode" && n.nodeName === nodeName);
@@ -197,7 +207,18 @@ function collectOptimizeTargets(body, targets) {
             }
             const target = { node, llmCall, tag: optimizeTag };
             target.promptValue = getPromptValue(target);
-            target.configKeys = optimizeTag.arguments.length === 0 ? ["prompt"] : optimizeTag.arguments;
+            if (optimizeTag.arguments.length === 0) {
+                target.configKeys = ["prompt"];
+            }
+            else {
+                target.configKeys = optimizeTag.arguments.map((a) => {
+                    if (a.type !== "variableName") {
+                        const where = a.loc ? ` (line ${a.loc.line}, col ${a.loc.col})` : "";
+                        throw new Error(`@optimize(...) arguments must be plain config-key identifiers${where}; got ${a.type}.`);
+                    }
+                    return a.value;
+                });
+            }
             targets.push(target);
         }
     }

package/dist/lib/cli/optimize.test.js

@@ -81,7 +81,12 @@ node main(msg: string): string {
         expect(tag).toMatchObject({
             type: "tag",
             name: "goal",
-            arguments: ["Classify messages accurately"],
+            arguments: [
+                {
+                    type: "string",
+                    segments: [{ type: "text", value: "Classify messages accurately" }],
+                },
+            ],
         });
     });
     it("returns null when no @goal tag exists on the node", () => {

package/dist/lib/cli/runBundledAgent.js

@@ -1,14 +1,22 @@
 import { compile, compiledOutputNodeArgs } from "./commands.js";
 import { spawn } from "child_process";
+import * as fs from "fs";
 import * as path from "path";
 const currentDir = path.dirname(new URL(import.meta.url).pathname);
 export function runBundledAgent(config, agentName, args = []) {
     const agentDir = path.resolve(currentDir, `../agents/${agentName}`);
     const agencyFile = path.join(agentDir, "agent.agency");
-    // The compiled agent.js already includes a top-level invocation of `main()`,
-    // so we run it directly. (Older code expected a hand-written run.js wrapper
-    // that no longer exists.)
-    const runFile = compile(config, agencyFile);
+    const precompiledFile = path.join(agentDir, "agent.js");
+    // Prefer the precompiled agent.js produced by `make agents` so users
+    // don't pay the compile cost on every invocation. Falls back to a
+    // fresh compile if the bundle hasn't been built yet.
+    let runFile;
+    if (fs.existsSync(precompiledFile)) {
+        runFile = precompiledFile;
+    }
+    else {
+        runFile = compile(config, agencyFile);
+    }
     if (runFile === null) {
         console.error(`Failed to compile agent ${agentName}.`);
         process.exit(1);

package/dist/lib/cli/schedule/index.js

@@ -17,6 +17,7 @@ function cronIntervalMinutes(cron) {
     return Number.POSITIVE_INFINITY;
 }
 export async function promptScheduleOverwrite(name) {
+    // eslint-disable-next-line no-restricted-syntax -- lazy load to avoid pulling in `prompts` for non-interactive flows
     const prompts = (await import("prompts")).default;
     const { overwrite } = await prompts({
         type: "confirm",

package/dist/lib/cli/serve.js

@@ -53,6 +53,7 @@ function compileForServe(file) {
 }
 async function loadAndDiscover(compileResult) {
     const moduleUrl = pathToFileURL(path.resolve(compileResult.outputPath)).href;
+    // eslint-disable-next-line no-restricted-syntax -- compiled module URL is only known at runtime
     const mod = await import(moduleUrl);
     const moduleExports = mod;
     const toolRegistry = moduleExports.__toolRegistry ?? {};

package/dist/lib/cli/test.js

@@ -117,10 +117,11 @@ function exitIfSignal(e) {
         process.exit(1);
     }
 }
+// eslint-disable-next-line max-lines-per-function -- legacy CLI entrypoint slated for incremental refactor
 export async function fixtures(config, target) {
-    let { filename, nodeName } = target
-        ? parseTarget(target)
-        : await promptForTarget();
+    const resolved = target ? parseTarget(target) : await promptForTarget();
+    const { filename } = resolved;
+    let { nodeName } = resolved;
     const contents = readFile(filename);
     const parsed = parseAgency(contents);
     if (!parsed.success) {
@@ -139,7 +140,7 @@ export async function fixtures(config, target) {
     }
     // Find the selected node and prompt for args
     const selectedNode = nodes.find((n) => n.nodeName === nodeName);
-    let { hasArgs, argsString } = await promptForArgs(selectedNode);
+    const { hasArgs, argsString } = await promptForArgs(selectedNode);
     console.log("Running program from entrypoint", nodeName);
     let json = executeNode({
         config,
@@ -367,6 +368,7 @@ async function runSingleTest(config, testFile, testCase, timeoutMs, signal, log)
             timeoutMs,
             signal,
             llmMocks: testCase.llmMocks,
+            useTestLLMProvider: testCase.useTestLLMProvider,
         });
         if (result.stdout)
             log(result.stdout.trimEnd());
@@ -542,7 +544,8 @@ async function runTestFile(config, testFile, suite) {
             // the judge itself is an LLM call without a mock. Skip these so CI
             // gets a clear `skipped` rather than a confusing "no mock provided"
             // failure.
-            if (process.env.AGENCY_USE_TEST_LLM_PROVIDER &&
+            if ((process.env.AGENCY_USE_TEST_LLM_PROVIDER ||
+                testCase.useTestLLMProvider) &&
                 testCase.evaluationCriteria.some((c) => c.type === "llmJudge")) {
                 log(color.yellow(`  ⊘ Skipped (LLM-as-judge requires real client)`));
                 skipped++;
@@ -730,9 +733,19 @@ async function runTsTestDir(config, dir) {
         // DeterministicClient. When the file is absent under deterministic
         // mode we still set the env var to "[]" so any llm() call fails
         // cleanly instead of falling through to the real OpenAI client.
+        //
+        // Activate the deterministic client whenever EITHER:
+        //   - the suite-wide AGENCY_USE_TEST_LLM_PROVIDER env var is set
+        //     (typical for PR CI), OR
+        //   - a `useTestLLMProvider` marker file sits next to test.js
+        //     (mirrors the per-test flag in .test.json — lets a single
+        //     agency-js test pin itself to the deterministic provider even
+        //     on push-to-main CI where the env var is unset).
         const mocksFile = path.join(dir, "llmMocks.json");
+        const useDeterministic = !!process.env.AGENCY_USE_TEST_LLM_PROVIDER ||
+            fs.existsSync(path.join(dir, "useTestLLMProvider"));
         let mocksEnv = {};
-        if (process.env.AGENCY_USE_TEST_LLM_PROVIDER) {
+        if (useDeterministic) {
             const mocks = fs.existsSync(mocksFile)
                 ? fs.readFileSync(mocksFile, "utf-8")
                 : "[]";

package/dist/lib/cli/util.d.ts

@@ -37,8 +37,9 @@ type ExecuteNodeArgs = {
     timeoutMs?: number;
     signal?: AbortSignal;
     llmMocks?: LLMMock[];
+    useTestLLMProvider?: boolean;
 };
-export declare function executeNodeAsync({ config, agencyFile, nodeName, hasArgs, argsString, interruptHandlers, timeoutMs, signal, llmMocks, }: ExecuteNodeArgs): Promise<{
+export declare function executeNodeAsync({ config, agencyFile, nodeName, hasArgs, argsString, interruptHandlers, timeoutMs, signal, llmMocks, useTestLLMProvider, }: ExecuteNodeArgs): Promise<{
     data: any;
     stdout: string;
     stderr: string;

package/dist/lib/cli/util.js

@@ -24,7 +24,7 @@ export function parseTarget(target) {
 }
 export async function promptForTarget() {
     let filename = "";
-    let nodeName = "";
+    const nodeName = "";
     // Find all .agency files in the current directory
     const agencyFiles = fs
         .readdirSync(process.cwd())
@@ -117,7 +117,7 @@ export function resolveCompiledFile(distDir, agencyFile) {
     }
     return compiledPath;
 }
-export async function executeNodeAsync({ config, agencyFile, nodeName, hasArgs, argsString, interruptHandlers, timeoutMs, signal, llmMocks, }) {
+export async function executeNodeAsync({ config, agencyFile, nodeName, hasArgs, argsString, interruptHandlers, timeoutMs, signal, llmMocks, useTestLLMProvider, }) {
     let evaluateFile = "";
     let resultsFile = "";
     try {
@@ -163,10 +163,18 @@ export async function executeNodeAsync({ config, agencyFile, nodeName, hasArgs,
         // Pass mocks to the subprocess as a JSON string in an env var. The
         // compiled module's imports template auto-activates DeterministicClient
         // when AGENCY_LLM_MOCKS is set. No temp file, no cleanup needed.
-        // When AGENCY_USE_TEST_LLM_PROVIDER=1, always set the env var (even to
-        // an empty list) so the deterministic client takes over — otherwise a
-        // missing llmMocks would silently fall through to the real OpenAI client.
-        const mocksEnv = process.env.AGENCY_USE_TEST_LLM_PROVIDER
+        //
+        // Activate the deterministic client whenever EITHER:
+        //   - the suite-wide AGENCY_USE_TEST_LLM_PROVIDER env var is set
+        //     (typical for PR CI), OR
+        //   - the per-test `useTestLLMProvider` flag is true (lets a single
+        //     test pin itself to the deterministic provider even on
+        //     push-to-main CI where the env var is unset).
+        // Setting the env var to "[]" when no mocks are provided still
+        // activates the deterministic client so any llm() call fails cleanly
+        // instead of falling through to the real OpenAI client.
+        const useDeterministic = !!process.env.AGENCY_USE_TEST_LLM_PROVIDER || !!useTestLLMProvider;
+        const mocksEnv = useDeterministic
             ? { AGENCY_LLM_MOCKS: JSON.stringify(llmMocks ?? []) }
             : {};
         const { stdout, stderr } = await execFileAsync("node", [evaluateFile], {

package/dist/lib/compilationUnit.d.ts

@@ -1,4 +1,4 @@
-import type { AgencyProgram, ClassDefinition, FunctionDefinition, FunctionParameter, GraphNodeDefinition, Scope, VariableType } from "./types.js";
+import type { AgencyProgram, FunctionDefinition, FunctionParameter, GraphNodeDefinition, Scope, Tag, TypeAliasEntry, TypeParam, ValueParam, VariableType } from "./types.js";
 import type { ImportNodeStatement, ImportStatement } from "./types/importStatement.js";
 import type { SymbolTable, InterruptKind } from "./symbolTable.js";
 export declare const GLOBAL_SCOPE_KEY = "global";
@@ -9,13 +9,13 @@ export declare const GLOBAL_SCOPE_KEY = "global";
  */
 export declare class ScopedTypeAliases {
     private readonly byScope;
-    constructor(initial?: Record<string, Record<string, VariableType>>);
-    add(scopeKey: string, name: string, type: VariableType): void;
-    get(scopeKey: string): Record<string, VariableType> | undefined;
+    constructor(initial?: Record<string, Record<string, TypeAliasEntry>>);
+    add(scopeKey: string, name: string, body: VariableType, typeParams?: TypeParam[], tags?: Tag[], valueParams?: ValueParam[]): void;
+    get(scopeKey: string): Record<string, TypeAliasEntry> | undefined;
     /** Flat map of every alias visible in `scopeKey`; scope-local wins. */
-    visibleIn(scopeKey: string): Record<string, VariableType>;
+    visibleIn(scopeKey: string): Record<string, TypeAliasEntry>;
     /** Iterate over every (scopeKey, aliases-in-that-scope) pair. */
-    scopes(): [string, Record<string, VariableType>][];
+    scopes(): [string, Record<string, TypeAliasEntry>][];
     clone(): ScopedTypeAliases;
 }
 /**
@@ -54,7 +54,6 @@ export type CompilationUnit = {
      * variable diagnostics quiet without pretending we know their types.
      */
     jsImportedNames: Record<string, true>;
-    classDefinitions: Record<string, ClassDefinition>;
     /** Original source text. Used by the typechecker to locate
      * `// @tc-nocheck` / `// @tc-ignore` directives. Optional because
      * many callers (including most tests) construct the AST directly. */

package/dist/lib/compilationUnit.js

@@ -1,4 +1,5 @@
 import { getImportedNames } from "./types/importStatement.js";
+import { collectTypeAliasTags } from "./symbolTable.js";
 import { walkNodes } from "./utils/node.js";
 import { resultTypeForValidation } from "./typeChecker/validation.js";
 import { visitTypes } from "./typeChecker/typeWalker.js";
@@ -18,10 +19,17 @@ export class ScopedTypeAliases {
             }
         }
     }
-    add(scopeKey, name, type) {
+    add(scopeKey, name, body, typeParams, tags, valueParams) {
         if (!this.byScope[scopeKey])
             this.byScope[scopeKey] = {};
-        this.byScope[scopeKey][name] = type;
+        const entry = { body };
+        if (typeParams)
+            entry.typeParams = typeParams;
+        if (valueParams)
+            entry.valueParams = valueParams;
+        if (tags && tags.length > 0)
+            entry.tags = tags;
+        this.byScope[scopeKey][name] = entry;
     }
     get(scopeKey) {
         return this.byScope[scopeKey];
@@ -65,7 +73,6 @@ export function buildCompilationUnit(program, symbolTable, fromFile, sourceText)
         importStatements: [],
         importedFunctions: {},
         jsImportedNames: {},
-        classDefinitions: {},
         safeFunctions: {},
         sourceText,
     };
@@ -83,14 +90,6 @@ export function buildCompilationUnit(program, symbolTable, fromFile, sourceText)
             case "importNodeStatement":
                 unit.importedNodes.push(node);
                 break;
-            case "classDefinition":
-                unit.classDefinitions[node.className] = node;
-                for (const method of node.methods) {
-                    if (method.safe) {
-                        unit.safeFunctions[`${node.className}.${method.name}`] = true;
-                    }
-                }
-                break;
             case "importStatement":
                 unit.importStatements.push(node);
                 for (const nameType of node.importedNames) {
@@ -116,11 +115,18 @@ export function buildCompilationUnit(program, symbolTable, fromFile, sourceText)
                 break;
         }
     }
+    // Tags on local typeAlias nodes are only attached after the preprocessor
+    // runs (which happens AFTER buildCompilationUnit). Pre-collect them here
+    // so cross-module annotation propagation works in the first pass.
+    const localAliasTags = collectTypeAliasTags(program);
     // Deep walk: collect every type alias keyed by its enclosing scope.
     for (const { node, scopes } of walkNodes(program.nodes)) {
         const key = scopeKey(scopes[scopes.length - 1]);
         if (node.type === "typeAlias") {
-            unit.typeAliases.add(key, node.aliasName, node.aliasedType);
+            const tags = node.tags && node.tags.length > 0
+                ? node.tags
+                : localAliasTags[node.aliasName];
+            unit.typeAliases.add(key, node.aliasName, node.aliasedType, node.typeParams, tags, node.valueParams);
         }
     }
     // Stitch in cross-file information from imports. Entries are only added
@@ -147,6 +153,7 @@ export function buildCompilationUnit(program, symbolTable, fromFile, sourceText)
                         originFile: r.file,
                     };
                     for (const p of r.symbol.parameters) {
+                        // eslint-disable-next-line max-depth -- collecting alias seeds from imported function params
                         if (p.typeHint)
                             aliasSeeds.push({ type: p.typeHint, preferFile: r.file });
                     }
@@ -157,7 +164,7 @@ export function buildCompilationUnit(program, symbolTable, fromFile, sourceText)
                     unit.safeFunctions[r.localName] = true;
                 }
                 if (r.symbol.kind === "type") {
-                    unit.typeAliases.add(GLOBAL_SCOPE_KEY, r.localName, r.symbol.aliasedType);
+                    unit.typeAliases.add(GLOBAL_SCOPE_KEY, r.localName, r.symbol.aliasedType, r.symbol.typeParams, r.symbol.tags, r.symbol.valueParams);
                     // Imported type's body may reference other aliases from its
                     // module — pull those transitively too.
                     aliasSeeds.push({ type: r.symbol.aliasedType, preferFile: r.file });
@@ -224,7 +231,7 @@ function pullTransitiveAliases(unit, symbolTable, seeds) {
         const found = resolveTypeFromFile(symbolTable, name, preferFile);
         if (!found)
             continue;
-        unit.typeAliases.add(GLOBAL_SCOPE_KEY, name, found.aliasedType);
+        unit.typeAliases.add(GLOBAL_SCOPE_KEY, name, found.aliasedType, found.typeParams, found.tags, found.valueParams);
         // Nested aliases referenced by this type should resolve in the file
         // the type was actually found in (not the original preferFile) — the
         // body's references are scoped to that module.
@@ -245,13 +252,25 @@ function resolveTypeFromFile(symbolTable, name, preferFile) {
     if (preferFile) {
         const fileSym = symbolTable.getFile(preferFile)?.[name];
         if (fileSym?.kind === "type") {
-            return { aliasedType: fileSym.aliasedType, file: preferFile };
+            return {
+                aliasedType: fileSym.aliasedType,
+                typeParams: fileSym.typeParams,
+                valueParams: fileSym.valueParams,
+                tags: fileSym.tags,
+                file: preferFile,
+            };
         }
     }
     for (const file of symbolTable.filePaths()) {
         const sym = symbolTable.getFile(file)?.[name];
         if (sym?.kind === "type") {
-            return { aliasedType: sym.aliasedType, file };
+            return {
+                aliasedType: sym.aliasedType,
+                typeParams: sym.typeParams,
+                valueParams: sym.valueParams,
+                tags: sym.tags,
+                file,
+            };
         }
     }
     return undefined;

package/dist/lib/compilationUnit.test.js

@@ -30,7 +30,7 @@ describe("buildCompilationUnit", () => {
         };
         const info = buildCompilationUnit(program);
         expect(info.typeAliases.get(GLOBAL_SCOPE_KEY)).toEqual({
-            Name: { type: "primitiveType", value: "string" },
+            Name: { body: { type: "primitiveType", value: "string" } },
         });
     });
     it("collects type aliases inside a graph node body", () => {
@@ -53,7 +53,7 @@ describe("buildCompilationUnit", () => {
         };
         const info = buildCompilationUnit(program);
         expect(info.typeAliases.get("node:start")).toEqual({
-            LocalType: { type: "primitiveType", value: "number" },
+            LocalType: { body: { type: "primitiveType", value: "number" } },
         });
         expect(info.typeAliases.get(GLOBAL_SCOPE_KEY)?.["LocalType"]).toBeUndefined();
     });
@@ -83,7 +83,7 @@ describe("buildCompilationUnit", () => {
         const info = buildCompilationUnit(program);
         const visible = info.typeAliases.visibleIn("function:fn");
         // Function-scoped T overrides global T
-        expect(visible["T"]).toEqual({ type: "primitiveType", value: "number" });
+        expect(visible["T"]).toEqual({ body: { type: "primitiveType", value: "number" } });
     });
     it("collects graph nodes", () => {
         const program = {
@@ -171,36 +171,4 @@ describe("buildCompilationUnit", () => {
         const info = buildCompilationUnit(program);
         expect(info.functionDefinitions["test"]).toBe(funcNode);
     });
-    it("registers safe class methods in safeFunctions", () => {
-        const program = {
-            type: "agencyProgram",
-            nodes: [
-                {
-                    type: "classDefinition",
-                    className: "Math",
-                    fields: [{ type: "classField", name: "x", typeHint: { type: "primitiveType", value: "number" } }],
-                    methods: [
-                        {
-                            type: "classMethod",
-                            name: "add",
-                            parameters: [],
-                            body: [],
-                            returnType: { type: "primitiveType", value: "number" },
-                            safe: true,
-                        },
-                        {
-                            type: "classMethod",
-                            name: "save",
-                            parameters: [],
-                            body: [],
-                            returnType: { type: "primitiveType", value: "number" },
-                        },
-                    ],
-                },
-            ],
-        };
-        const info = buildCompilationUnit(program);
-        expect(info.safeFunctions["Math.add"]).toBe(true);
-        expect(info.safeFunctions["Math.save"]).toBeUndefined();
-    });
 });