@telorun/analyzer 0.12.1 → 0.13.0

package/src/analyzer.ts

@@ -1,6 +1,6 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-import { defaultRegistry, walkCelExpressions } from "@telorun/templating";
+import { defaultRegistry, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver } from "./alias-resolver.js";
 import { AnalysisRegistry } from "./analysis-registry.js";
 import {
@@ -12,6 +12,7 @@ import { DefinitionRegistry } from "./definition-registry.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kernel-globals.js";
 import { computeSuggestKind } from "./kind-suggest.js";
+import { visitManifest } from "./manifest-visitor.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
@@ -25,6 +26,7 @@ import {
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
+  extractContextsFromSchema,
   getManifestItem,
   pathMatchesScope,
   resolveContextAnnotations,
@@ -34,6 +36,7 @@ import { validateExtends } from "./validate-extends.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
+import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
 const SELF_PREFIX = "Self.";
@@ -187,56 +190,6 @@ function manifestRootForResolver(
   };
 }
 
-/**
- * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
- * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
- * the same format the analyzer uses for CEL context validation.
- *
- * Result is sorted by scope specificity (longer scope first) so that the
- * per-expression resolver's first-match-wins logic picks the most-specific
- * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
- * could shadow a narrower descendant scope whose activation differs.
- */
-function extractContextsFromSchema(
-  schema: Record<string, any>,
-  path = "$",
-): Array<{ scope: string; schema: Record<string, any> }> {
-  const all = collectContexts(schema, path);
-  return all.sort((a, b) => b.scope.length - a.scope.length);
-}
-
-function collectContexts(
-  schema: Record<string, any>,
-  path: string,
-): Array<{ scope: string; schema: Record<string, any> }> {
-  if (!schema || typeof schema !== "object") return [];
-  const results: Array<{ scope: string; schema: Record<string, any> }> = [];
-
-  if (schema["x-telo-context"]) {
-    results.push({ scope: path, schema: schema["x-telo-context"] });
-  }
-
-  if (schema.properties) {
-    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
-      results.push(...collectContexts(value, `${path}.${key}`));
-    }
-  }
-
-  if (schema.items && typeof schema.items === "object") {
-    results.push(...collectContexts(schema.items, `${path}[*]`));
-  }
-
-  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
-    if (Array.isArray(schema[key])) {
-      for (const subschema of schema[key]) {
-        results.push(...collectContexts(subschema, path));
-      }
-    }
-  }
-
-  return results;
-}
-
 /** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
  *  Non-refs and unresolved refs pass through unchanged. */
 function resolveLocalRef(
@@ -439,20 +392,31 @@ function collectCelTypeIssues(
   manifest: ResourceManifest,
   baseTypedEnv: Environment,
   rootEnv: Environment,
+  rootModuleManifest?: ResourceManifest,
 ): SchemaIssue[] {
   const issues: SchemaIssue[] = [];
 
-  if (typeof data === "string" && CEL_PURE_RE.test(data)) {
-    const exprMatch = data.match(CEL_EXPR_RE);
-    if (exprMatch) {
-      const expr = exprMatch[1].trim();
+  // A pure CEL value type-checks the same regardless of surface form: a
+  // `${{ … }}` string and a `!cel`-tagged sentinel must behave identically.
+  let celExpr: string | undefined;
+  if (isTaggedSentinel(data)) {
+    // Non-CEL engines (e.g. `!literal`) are analyzed by their own engine pass.
+    if (data.engine !== "cel") return issues;
+    celExpr = data.source;
+  } else if (typeof data === "string" && CEL_PURE_RE.test(data)) {
+    celExpr = data.match(CEL_EXPR_RE)?.[1]?.trim();
+  }
+
+  if (celExpr !== undefined) {
+    {
+      const expr = celExpr;
 
       // Merge x-telo-context variables for this path if applicable
       let typedEnv = baseTypedEnv;
       if (definition.schema) {
         for (const ctx of extractContextsFromSchema(definition.schema)) {
           if (!pathMatchesScope(path, ctx.scope)) continue;
-          typedEnv = buildTypedCelEnvironment(rootEnv, manifest, ctx.schema);
+          typedEnv = buildTypedCelEnvironment(rootEnv, manifest, ctx.schema, rootModuleManifest);
           break;
         }
       }
@@ -475,8 +439,9 @@ function collectCelTypeIssues(
       } else if (checkResult?.valid && checkResult.type && schema) {
         const celType = checkResult.type.split("<")[0]!;
         if (!celTypeSatisfiesJsonSchema(celType, schema)) {
+          const expected = schema["x-telo-type"] ?? schema.type ?? "unknown";
           issues.push({
-            message: `CEL returns '${checkResult.type}' but field expects '${schema.type ?? "unknown"}'`,
+            message: `CEL returns '${checkResult.type}' but field expects '${expected}'`,
             path,
           });
         }
@@ -497,6 +462,7 @@ function collectCelTypeIssues(
           manifest,
           baseTypedEnv,
           rootEnv,
+          rootModuleManifest,
         ),
       );
     }
@@ -512,6 +478,7 @@ function collectCelTypeIssues(
           manifest,
           baseTypedEnv,
           rootEnv,
+          rootModuleManifest,
         ),
       );
     }
@@ -758,6 +725,13 @@ export class StaticAnalyzer {
     // recognises variables, secrets, resources, env automatically
     const kernelGlobals = buildKernelGlobalsSchema(allManifests);
 
+    // The module doc (Application/Library) carries the Application-only `ports`
+    // namespace; threaded into per-resource CEL typing so `${{ ports.X }}`
+    // resolves its nominal brand cross-doc.
+    const moduleManifest =
+      allManifests.find((mm) => mm.kind === "Telo.Application") ??
+      allManifests.find((mm) => mm.kind === "Telo.Library");
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       const filePath = (m.metadata as { source?: string } | undefined)?.source;
@@ -816,8 +790,17 @@ export class StaticAnalyzer {
               }
             : definition.schema;
         // Phase 1: CEL type checking — walk data+schema together, check env.check() return types
-        const baseTypedEnv = buildTypedCelEnvironment(this.celEnv, m);
-        const celIssues = collectCelTypeIssues(m, schema, "", definition, m, baseTypedEnv, this.celEnv);
+        const baseTypedEnv = buildTypedCelEnvironment(this.celEnv, m, undefined, moduleManifest);
+        const celIssues = collectCelTypeIssues(
+          m,
+          schema,
+          "",
+          definition,
+          m,
+          baseTypedEnv,
+          this.celEnv,
+          moduleManifest,
+        );
         // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
         const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
         const issues = [...celIssues, ...ajvIssues];
@@ -959,125 +942,127 @@ export class StaticAnalyzer {
       }
     }
 
-    // Validate CEL syntax and context variable access in all manifests
-    for (const m of allManifests) {
-      const resource = { kind: m.kind, name: m.metadata?.name as string };
-      const filePath = (m.metadata as { source?: string } | undefined)?.source;
-
-      const resolvedKind = aliases.resolveKind(m.kind);
-      const mDefinition =
-        defs.resolve(m.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
-
-      // Pre-compute step context for manifests with x-telo-step-context
-      const stepContextSchema = mDefinition?.schema
-        ? buildStepContextSchema(
-            m as Record<string, any>,
-            mDefinition.schema as Record<string, any>,
-            allManifests as Record<string, any>[],
-            defs,
-            aliases,
-          )
-        : undefined;
-
-      walkCelExpressions(m, "", (expr, path, engineName) => {
-        // Resolve the effective context for this expression's path. The
-        // engine receives a single closed schema and validates member-access
-        // chains against it; per-path resolution (step context, x-telo-context,
-        // kernel-globals merge) stays on the analyzer side because it depends
-        // on analyzer-internal state (definitions, aliases).
-        const contexts = mDefinition?.schema ? extractContextsFromSchema(mDefinition.schema) : [];
-        const invocationContext = (m.metadata as any)?.xTeloInvocationContext as
-          | Record<string, any>
-          | undefined;
-
-        let matchedContext: Record<string, any> | undefined;
-        let matchedScope: string | undefined;
-        for (const ctx of contexts) {
-          if (pathMatchesScope(path, ctx.scope)) {
-            matchedContext = ctx.schema;
-            matchedScope = ctx.scope;
-            break;
+    // Validate CEL syntax and context variable access in all manifests. The
+    // walker discovers every compiled CEL node by scanning the value tree and
+    // hands back the `x-telo-context` schema matched at the enclosing path; the
+    // per-path resolution (step context, kernel-globals merge, x-telo-context-*
+    // annotation resolution) stays here because it depends on analyzer-internal
+    // state (definitions, aliases, the typed CEL env).
+    // Per-resource state computed at enter and read by that resource's CEL
+    // sites. The manifest / resource / filePath come straight off each CelSite's
+    // `source` (no need to capture them); only the derived step / invocation
+    // context — which require analyzer state to build — are stashed here.
+    let celStepContextSchema: Record<string, any> | undefined;
+    let celInvocationContext: Record<string, any> | undefined;
+
+    visitManifest(
+      allManifests,
+      defs,
+      {
+        onResourceEnter: (e) => {
+          const m = e.source;
+          celInvocationContext = (m.metadata as any)?.xTeloInvocationContext as
+            | Record<string, any>
+            | undefined;
+          celStepContextSchema = e.definition?.schema
+            ? buildStepContextSchema(
+                m as Record<string, any>,
+                e.definition.schema as Record<string, any>,
+                allManifests as Record<string, any>[],
+                defs,
+                aliases,
+              )
+            : undefined;
+        },
+        onCel: (e) => {
+          const m = e.source;
+          const resource = { kind: m.kind, name: m.metadata?.name as string };
+          const filePath = (m.metadata as { source?: string } | undefined)?.source;
+          const { expr, path, engineName, matchedScope } = e;
+
+          let matchedContext: Record<string, any> | undefined =
+            e.contextSchema ?? celInvocationContext;
+
+          if (celStepContextSchema) {
+            const base =
+              matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
+            matchedContext = {
+              ...base,
+              properties: {
+                ...(base.properties ?? {}),
+                steps: celStepContextSchema,
+              },
+            };
           }
-        }
-        if (!matchedContext) matchedContext = invocationContext;
-
-        if (stepContextSchema) {
-          const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
-          matchedContext = {
-            ...base,
-            properties: {
-              ...(base.properties ?? {}),
-              steps: stepContextSchema,
-            },
-          };
-        }
 
-        let effectiveContext: Record<string, any> | null = null;
-        if (matchedContext) {
-          const manifestItem = matchedScope
-            ? getManifestItem(path, matchedScope, m as Record<string, any>)
-            : (m as Record<string, any>);
-          const rootForResolver = manifestRootForResolver(
-            m as Record<string, any>,
-            defs,
-            aliases,
-            allManifests as Record<string, any>[],
-          );
-          const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
-            manifestRoot: rootForResolver,
-            defs,
-            aliases,
-            allManifests: allManifests as Record<string, any>[],
-          });
-          effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
-        }
-
-        const engine = defaultRegistry().get(engineName);
-        if (!engine) {
-          // No registered engine owns this tag — the expression would go
-          // entirely unanalyzed. Surface it rather than skipping silently.
-          diagnostics.push({
-            severity: DiagnosticSeverity.Error,
-            code: "UNKNOWN_ENGINE",
-            source: SOURCE,
-            message: `${m.kind}/${resource.name}: no templating engine registered for '!${engineName}' at '${path}'.`,
-            data: { resource, filePath, path },
-          });
-          return;
-        }
-        const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
-        for (const f of findings) {
-          if (f.code === "CEL_SYNTAX_ERROR") {
-            diagnostics.push({
-              severity: DiagnosticSeverity.Error,
-              code: "CEL_SYNTAX_ERROR",
-              source: SOURCE,
-              message: `CEL syntax error at ${path}: ${f.message}`,
-              data: { resource, filePath, path },
-            });
-          } else if (f.code === "CEL_UNKNOWN_FIELD") {
-            diagnostics.push({
-              severity: DiagnosticSeverity.Error,
-              code: "CEL_UNKNOWN_FIELD",
-              source: SOURCE,
-              message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
-              data: { resource, filePath, path },
+          let effectiveContext: Record<string, any> | null = null;
+          if (matchedContext) {
+            const manifestItem = matchedScope
+              ? getManifestItem(path, matchedScope, m as Record<string, any>)
+              : (m as Record<string, any>);
+            const rootForResolver = manifestRootForResolver(
+              m as Record<string, any>,
+              defs,
+              aliases,
+              allManifests as Record<string, any>[],
+            );
+            const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
+              manifestRoot: rootForResolver,
+              defs,
+              aliases,
+              allManifests: allManifests as Record<string, any>[],
             });
-          } else {
-            // Unknown code from a future engine — pass the message through,
-            // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
-            // filters can still bucket it.
+            effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
+          }
+
+          const engine = defaultRegistry().get(engineName);
+          if (!engine) {
+            // No registered engine owns this tag — the expression would go
+            // entirely unanalyzed. Surface it rather than skipping silently.
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
-              code: f.code ?? "ENGINE_DIAGNOSTIC",
+              code: "UNKNOWN_ENGINE",
               source: SOURCE,
-              message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+              message: `${m.kind}/${resource.name}: no templating engine registered for '!${engineName}' at '${path}'.`,
               data: { resource, filePath, path },
             });
+            return;
           }
-        }
-      });
-    }
+          const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
+          for (const f of findings) {
+            if (f.code === "CEL_SYNTAX_ERROR") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CEL_SYNTAX_ERROR",
+                source: SOURCE,
+                message: `CEL syntax error at ${path}: ${f.message}`,
+                data: { resource, filePath, path },
+              });
+            } else if (f.code === "CEL_UNKNOWN_FIELD") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CEL_UNKNOWN_FIELD",
+                source: SOURCE,
+                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
+                data: { resource, filePath, path },
+              });
+            } else {
+              // Unknown code from a future engine — pass the message through,
+              // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
+              // filters can still bucket it.
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: f.code ?? "ENGINE_DIAGNOSTIC",
+                source: SOURCE,
+                message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+                data: { resource, filePath, path },
+              });
+            }
+          }
+        },
+      },
+      { aliases },
+    );
 
     // Validate resource references (Phase 3)
     diagnostics.push(
@@ -1093,6 +1078,9 @@ export class StaticAnalyzer {
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 
+    // Warn about declared variables / secrets / ports that no CEL references.
+    diagnostics.push(...validateUnusedDeclarations(allManifests, this.celEnv));
+
     // Reroute diagnostics on synthetic (inline-extracted) resources back to
     // the chain root so position-index lookups land on the parent doc.
     return rewriteSyntheticOrigins(diagnostics, allManifests);

package/src/builtins.ts

@@ -279,6 +279,31 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
+        // Inbound ports the Application listens on. A name-keyed map mirroring
+        // `variables`: each entry binds a host env var (`env:`) that supplies a
+        // port integer (implicitly typed `integer`, 1–65535), with an optional
+        // `default:` used when the env var is unset. `protocol:` (default `tcp`)
+        // selects the transport — the runner reads this list to know the
+        // exposed ports before launch, and the analyzer brands the resolved
+        // `ports.<name>` value (tcp → TcpPort, udp → UdpPort) for static wiring
+        // checks. Application-only. See kernel/nodejs/src/application-env.ts.
+        ports: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env"],
+            properties: {
+              env: { type: "string" },
+              protocol: {
+                type: "string",
+                enum: ["tcp", "udp"],
+                default: "tcp",
+              },
+              default: { type: "integer", minimum: 1, maximum: 65535 },
+            },
+            additionalProperties: false,
+          },
+        },
       },
       required: ["metadata"],
       additionalProperties: false,

package/src/cel-environment.ts

@@ -1,6 +1,13 @@
 import { Environment } from "@marcbachmann/cel-js";
 import type { ResourceManifest } from "@telorun/sdk";
-import { jsonSchemaToCelType } from "./schema-compat.js";
+import { jsonSchemaToCelType, VALUE_BRAND_BASE } from "./schema-compat.js";
+
+/** Transport protocol on a `ports` entry → the nominal CEL brand its resolved
+ *  value carries. Mirrors the `protocol` enum in the Application schema. */
+const PORT_PROTOCOL_BRAND: Record<string, string> = {
+  tcp: "TcpPort",
+  udp: "UdpPort",
+};
 
 export { buildCelEnvironment } from "@telorun/templating";
 export type { CelHandlers } from "@telorun/templating";
@@ -19,10 +26,23 @@ export function buildTypedCelEnvironment(
   baseEnv: Environment,
   manifest: ResourceManifest,
   extraContextSchema?: Record<string, any> | null,
+  // The `ports` namespace is Application-only and lives on the module doc, not
+  // on the resource being analyzed. When validating a resource, the caller
+  // passes the module manifest here so `${{ ports.X }}` types cross-doc.
+  rootModuleManifest?: ResourceManifest,
 ): Environment {
   try {
     const env = baseEnv.clone();
 
+    // Register nominal value brands (TcpPort/UdpPort/…) on the *clone* so the
+    // type-checker can distinguish structurally-identical values. The base env
+    // (shared with the kernel runtime) is untouched — a branded value flows as
+    // a plain integer at runtime, so only static checking needs these. cel-js
+    // auto-generates a field-less wrapper class; no runtime constructor needed.
+    for (const brand of Object.keys(VALUE_BRAND_BASE)) {
+      (env as any).registerType(brand, { fields: {} });
+    }
+
     // Build typed ObjectSchema from manifest.variables if it looks like a schema map
     const vars = (manifest as Record<string, unknown>).variables;
     if (vars !== null && typeof vars === "object" && !Array.isArray(vars)) {
@@ -42,6 +62,27 @@ export function buildTypedCelEnvironment(
       env.registerVariable("variables", "map");
     }
 
+    // `ports` namespace: each entry types as the brand its `protocol` selects
+    // (tcp → TcpPort, udp → UdpPort), so `${{ ports.http }}` carries a nominal
+    // type that consuming fields can check against.
+    const portsManifest = ((rootModuleManifest ?? manifest) as Record<string, unknown>).ports;
+    if (portsManifest !== null && typeof portsManifest === "object" && !Array.isArray(portsManifest)) {
+      const portEntries = Object.entries(portsManifest as Record<string, any>).filter(
+        ([, v]) => v !== null && typeof v === "object" && !Array.isArray(v),
+      );
+      if (portEntries.length > 0) {
+        const schema: Record<string, string> = {};
+        for (const [k, v] of portEntries) {
+          schema[k] = PORT_PROTOCOL_BRAND[(v as { protocol?: string }).protocol ?? "tcp"] ?? "int";
+        }
+        (env as any).registerVariable({ name: "ports", schema });
+      } else {
+        env.registerVariable("ports", "map");
+      }
+    } else {
+      env.registerVariable("ports", "map");
+    }
+
     env.registerVariable("secrets", "map");
     env.registerVariable("resources", "map");
     env.registerVariable("env", "map");

package/src/dependency-graph.ts

@@ -2,7 +2,7 @@ import type { ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
-import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+import { visitManifest } from "./manifest-visitor.js";
 import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 export interface ResourceNode {
@@ -57,64 +57,49 @@ export function buildDependencyGraph(
   const deps = new Map<string, Set<string>>();
   for (const key of nodes.keys()) deps.set(key, new Set());
 
-  for (const r of resources) {
-    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
-
-    const sourceKey = nodeKey(r.kind, r.metadata.name as string);
-    // Use the expanded map so refs nested behind x-telo-schema-from contribute
-    // edges to the DAG. Without these, a parent (e.g. Http.Server) can init
-    // before its extracted encoder and Phase 5 injection fires against a
-    // not-yet-created dependency.
-    const fieldMap =
-      aliases && aliasesByModule
-        ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
-        : registry.getFieldMapForKind(r.kind, aliases);
-    if (!fieldMap) continue;
-
-    // Collect names of resources declared inside scope fields — these are initialized
-    // on-demand at runtime, not at boot, so edges pointing to them are excluded from the DAG.
-    const scopedNames = new Set<string>();
-    for (const [scopeFieldPath, entry] of fieldMap) {
-      if (!isScopeEntry(entry)) continue;
-      const scopeVal = (r as Record<string, unknown>)[scopeFieldPath];
-      if (!Array.isArray(scopeVal)) continue;
-      for (const item of scopeVal) {
-        const name = (item as any)?.metadata?.name;
-        if (typeof name === "string") scopedNames.add(name);
-      }
-    }
-
-    for (const [fieldPath, entry] of fieldMap) {
-      if (!isRefEntry(entry)) continue;
-
-      for (const val of resolveFieldValues(r, fieldPath)) {
-        if (!val) continue;
-
-        // `!ref <name>` sentinel — look up the target's kind from the
-        // name (resources are unique by name) so the edge carries the
-        // concrete kind, matching the {kind, name} edge shape below.
+  // Names of resources declared inside the *current* resource's scope fields —
+  // initialized on-demand at runtime, not at boot, so edges pointing to them
+  // are excluded. Scoping is per-source-resource: an edge A → B is dropped only
+  // when B is declared inside A's own scope (the visitor's ScopeBoundary fires
+  // before that resource's RefSites, so this is set before any edge is added).
+  let scopedNames = new Set<string>();
+
+  // Expanded map so refs nested behind x-telo-schema-from contribute edges to
+  // the DAG. Without these, a parent (e.g. Http.Server) can init before its
+  // extracted encoder and Phase 5 injection fires against a not-yet-created
+  // dependency.
+  visitManifest(
+    resources,
+    registry,
+    {
+      onScope: (e) => {
+        scopedNames = e.enclosedNames;
+      },
+      onRef: (e) => {
+        const sourceKey = nodeKey(e.source.kind, e.source.metadata!.name as string);
+        const val = e.value;
+
+        // `!ref <name>` sentinel — look up the target's kind from the name
+        // (resources are unique by name) so the edge carries the concrete kind,
+        // matching the {kind, name} edge shape below.
         if (isRefSentinel(val)) {
           const refName = val.source;
-          if (scopedNames.has(refName)) continue;
+          if (scopedNames.has(refName)) return;
           const node = nodesByName.get(refName);
-          if (node) {
-            deps.get(sourceKey)!.add(nodeKey(node.kind, node.name));
-          }
-          continue;
+          if (node) deps.get(sourceKey)!.add(nodeKey(node.kind, node.name));
+          return;
         }
 
-        if (typeof val !== "object") continue;
+        if (typeof val !== "object") return;
         const ref = val as Record<string, unknown>;
-        if (!ref.kind || !ref.name) continue;
-        // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG
-        if (scopedNames.has(ref.name as string)) continue;
+        if (!ref.kind || !ref.name) return;
+        if (scopedNames.has(ref.name as string)) return;
         const targetKey = nodeKey(ref.kind as string, ref.name as string);
-        if (nodes.has(targetKey)) {
-          deps.get(sourceKey)!.add(targetKey);
-        }
-      }
-    }
-  }
+        if (nodes.has(targetKey)) deps.get(sourceKey)!.add(targetKey);
+      },
+    },
+    { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: true },
+  );
 
   // --- Kahn's topological sort ---
   // in-degree[X] = number of X's dependencies (size of deps[X])

package/src/index.ts

@@ -9,6 +9,17 @@ export type {
     ParseError,
 } from "./loaded-types.js";
 export { flattenForAnalyzer, flattenLoadedModule } from "./flatten-for-analyzer.js";
+export { visitManifest } from "./manifest-visitor.js";
+export type {
+    CelSiteEvent,
+    ManifestVisitor,
+    RefSiteEvent,
+    ResourceEnterEvent,
+    ResourceExitEvent,
+    ScopeBoundaryEvent,
+    SchemaFromSiteEvent,
+    VisitOptions,
+} from "./manifest-visitor.js";
 export { Loader } from "./manifest-loader.js";
 export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";