@telorun/analyzer 0.3.0 → 0.4.0

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAsP/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAsPvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAKxF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAiB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuP/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAsSvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAKxF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAiB5F"}

package/dist/analyzer.js

@@ -9,6 +9,7 @@ import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
 import { extractAccessChains, getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, validateChainAgainstSchema, } from "./validate-cel-context.js";
+import { validateExtends } from "./validate-extends.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
@@ -210,9 +211,24 @@ export class StaticAnalyzer {
         // Register module identities and aliases.
         // The root module doc (Telo.Application or Telo.Library) provides its own
         // identity; imported modules surface their identity via resolvedModuleName/
-        // resolvedNamespace stamped onto the Telo.Import by the loader (so we don't
-        // need to include imported module manifests in the analysis set, avoiding false
-        // reference errors in the parent context).
+        // resolvedNamespace stamped onto the Telo.Import by the loader.
+        //
+        // Two alias scopes are tracked:
+        //  - `aliases` — the consumer's aliases, populated from Telo.Imports declared in
+        //    the entry manifest (its own module).
+        //  - `aliasesByModule` — per-imported-library aliases, populated from Telo.Imports
+        //    forwarded by the loader from inside imported libraries. A library may use
+        //    different alias names than the consumer for the same dependency; resolving
+        //    a forwarded def's `extends` / `capability` against the consumer's scope
+        //    would either fail or pick the wrong target. Each forwarded def is normalized
+        //    in its own library's scope.
+        const rootModules = new Set();
+        for (const m of manifests) {
+            if (isModuleKind(m.kind) && m.metadata?.name) {
+                rootModules.add(m.metadata.name);
+            }
+        }
+        const aliasesByModule = new Map();
         for (const m of manifests) {
             if (isModuleKind(m.kind)) {
                 const namespace = m.metadata.namespace ?? null;
@@ -226,26 +242,58 @@ export class StaticAnalyzer {
                 const exportedKinds = m.exports?.kinds ?? [];
                 const resolvedModuleName = m.metadata.resolvedModuleName;
                 const resolvedNamespace = m.metadata.resolvedNamespace;
+                const ownModule = m.metadata?.module;
                 if (alias && source) {
                     const targetModule = resolvedModuleName ?? source.split("/").filter(Boolean).pop() ?? source;
-                    aliases.registerImport(alias, targetModule, exportedKinds);
+                    // Module identity is registered globally so x-telo-ref resolution sees
+                    // transitively-imported modules regardless of which scope brought them in.
                     if (resolvedModuleName) {
                         defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
                     }
+                    // Alias registration is scoped: consumer imports vs. imported-library imports.
+                    if (!ownModule || rootModules.has(ownModule)) {
+                        aliases.registerImport(alias, targetModule, exportedKinds);
+                    }
+                    else {
+                        let libResolver = aliasesByModule.get(ownModule);
+                        if (!libResolver) {
+                            libResolver = new AliasResolver();
+                            aliasesByModule.set(ownModule, libResolver);
+                        }
+                        libResolver.registerImport(alias, targetModule, exportedKinds);
+                    }
                 }
             }
         }
-        // Register definitions from Telo.Definition resources.
-        // Normalize alias-prefixed `capability` to canonical form so extendedBy lookup works
-        // (e.g. "Workflow.Backend" → "workflow.Backend" when "Workflow" is a known alias).
+        // Register definitions from Telo.Definition AND Telo.Abstract resources.
+        // Abstracts declare contracts that implementations target via `extends` (canonical)
+        // or `capability: <AbstractKind>` (legacy). Until they're registered, validateReferences
+        // can't resolve x-telo-ref entries pointing at library-declared abstracts — so abstracts
+        // must go through register() too, not just the kernel builtins in the constructor.
+        //
+        // Normalize alias-prefixed `capability` and `extends` to canonical form using the
+        // declaring scope's resolver, so `extendedBy` is keyed by canonical kind regardless
+        // of alias choices. `capability` covers the legacy implements-this-abstract overload;
+        // `extends` is the canonical first-class form.
         for (const m of manifests) {
-            if (m.kind === "Telo.Definition") {
-                const def = m;
-                const resolvedCapability = def.capability
-                    ? (aliases.resolveKind(def.capability) ?? def.capability)
-                    : def.capability;
-                defs.register(resolvedCapability !== def.capability ? { ...def, capability: resolvedCapability } : def);
-            }
+            if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract")
+                continue;
+            const def = m;
+            const ownModule = def.metadata?.module;
+            const scopeResolver = ownModule && !rootModules.has(ownModule)
+                ? (aliasesByModule.get(ownModule) ?? new AliasResolver())
+                : aliases;
+            const resolvedCapability = def.capability
+                ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
+                : def.capability;
+            const resolvedExtends = def.extends
+                ? (scopeResolver.resolveKind(def.extends) ?? def.extends)
+                : def.extends;
+            const needsPatch = resolvedCapability !== def.capability || resolvedExtends !== def.extends;
+            const normalized = needsPatch
+                ? { ...def, capability: resolvedCapability, extends: resolvedExtends }
+                : def;
+            defs.register(normalized);
         }
         // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
         const allManifests = normalizeInlineResources(manifests, defs, aliases);
@@ -401,6 +449,8 @@ export class StaticAnalyzer {
         }
         // Validate resource references (Phase 3)
         diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs }));
+        // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
+        diagnostics.push(...validateExtends(allManifests, defs, aliases));
         // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
         diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
         return diagnostics;

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA4I/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAsJ/C,CAAC"}

package/dist/builtins.js

@@ -25,9 +25,13 @@ export const KERNEL_BUILTINS = [
                     additionalProperties: true,
                 },
                 capability: { type: "string" },
+                schema: { type: "object", additionalProperties: true },
             },
             required: ["metadata"],
-            additionalProperties: false,
+            // Telo.Abstract is an extension point by design — it must accept forward-compatible
+            // fields (e.g. inputType/outputType from the typed-abstracts plan) without requiring
+            // the analyzer to enumerate them here.
+            additionalProperties: true,
         },
     },
     {
@@ -53,6 +57,12 @@ export const KERNEL_BUILTINS = [
                 source: { type: "string" },
                 variables: { type: "object" },
                 secrets: { type: "object" },
+                runtime: {
+                    oneOf: [
+                        { type: "string" },
+                        { type: "array", items: { type: "string" } },
+                    ],
+                },
             },
             required: ["metadata", "source"],
             additionalProperties: false,

package/dist/definition-registry.d.ts

@@ -20,6 +20,7 @@ export declare class DefinitionRegistry {
      *  Used to compute definition $id values for the AJV schema store. */
     private readonly reverseIdentityMap;
     register(definition: ResourceDefinition): void;
+    private addExtendedBy;
     /** Register a module identity for x-telo-ref resolution.
      *  Call once per module doc (Telo.Application or Telo.Library) when the manifest is loaded.
      *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.

package/dist/definition-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG1F,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;6DACyD;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD;;0EAEsE;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAwB9C;;;yFAGqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgB1E;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;wFACoF;IACpF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;4FAQwF;IACxF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD,+FAA+F;IAC/F,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}
+{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG1F,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;6DACyD;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD;;0EAEsE;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAiC9C,OAAO,CAAC,aAAa;IASrB;;;yFAGqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgB1E;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;wFACoF;IACpF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;4FAQwF;IACxF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD,+FAA+F;IAC/F,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}

package/dist/definition-registry.js

@@ -28,14 +28,22 @@ export class DefinitionRegistry {
         const key = mod ? `${mod}.${name}` : name;
         this.defs.set(key, definition);
         this.fieldMaps.set(key, buildReferenceFieldMap(definition.schema ?? {}));
+        // `capability` populates extendedBy for backward-compat with the legacy pattern where
+        // a concrete definition overloaded `capability: <AbstractKind>` to mean "implements
+        // this abstract." The canonical pattern is `extends` (below). Both populate the index,
+        // unioned — so in-flight modules pre-migration keep working.
         if (definition.capability) {
-            const children = this.extendedBy.get(definition.capability);
-            if (children) {
-                children.push(key);
-            }
-            else {
-                this.extendedBy.set(definition.capability, [key]);
-            }
+            this.addExtendedBy(definition.capability, key);
+        }
+        // `extends` — first-class "implements-this-abstract" edge. Alias-form resolution
+        // happens in the analyzer before register() is called (analyzer.ts pre-resolves
+        // via aliases.resolveKind), so the value here is already the canonical kind string
+        // (e.g. "workflow.Backend"). If the analyzer could not resolve the alias (partial
+        // context, or the declaring file doesn't import the target's alias), the value
+        // stays as the original alias-prefixed form; validateExtends emits EXTENDS_MALFORMED
+        // or EXTENDS_UNKNOWN_TARGET depending on the case.
+        if (definition.extends) {
+            this.addExtendedBy(definition.extends, key);
         }
         // Auto-register the telo identity when any Telo built-in is registered.
         if (definition.kind === "Telo.Abstract" && mod === "Telo") {
@@ -47,6 +55,16 @@ export class DefinitionRegistry {
             this.tryRegisterSchema(mod, name, definition.schema);
         }
     }
+    addExtendedBy(parent, child) {
+        const children = this.extendedBy.get(parent);
+        if (children) {
+            if (!children.includes(child))
+                children.push(child);
+        }
+        else {
+            this.extendedBy.set(parent, [child]);
+        }
+    }
     /** Register a module identity for x-telo-ref resolution.
      *  Call once per module doc (Telo.Application or Telo.Library) when the manifest is loaded.
      *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.

package/dist/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAG/B;IAEJ,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,sBAAsB,GAAE,eAAe,EAAE,GAAG,iBAAsB;IAmB9E,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAKxC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqGnE,eAAe;YAoBf,eAAe;IAgEvB,iBAAiB,CACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;KAClD,GAAG,IAAI,CAAC;IAiCH,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAiEnE"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAG/B;IAEJ,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,sBAAsB,GAAE,eAAe,EAAE,GAAG,iBAAsB;IAmB9E,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAKxC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqGnE,eAAe;YAoBf,eAAe;IAgEvB,iBAAiB,CACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;KAClD,GAAG,IAAI,CAAC;IAiCH,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA2GnE"}

package/dist/manifest-loader.js

@@ -277,7 +277,30 @@ export class Loader {
     }
     async loadManifests(entryUrl) {
         const visited = new Set([entryUrl]);
+        // Cache resolved library identity per import URL so a Telo.Import re-encountered
+        // through a different chain still gets `resolvedModuleName` / `resolvedNamespace`
+        // stamped — without re-loading the target. The early `visited` short-circuit used
+        // to silently leave duplicate Telo.Imports unstamped, which broke alias resolution
+        // when the same library was imported by two different files in the same analysis set.
+        const libraryIdentityByUrl = new Map();
         const entry = await this.loadModule(entryUrl);
+        // Forward Telo.Definition, Telo.Abstract, AND Telo.Import docs from imported
+        // libraries to the analyzer so its downstream passes can see them:
+        //  - Definitions / Abstracts feed cross-package `x-telo-ref` resolution and
+        //    `extends` target validation.
+        //  - Imports feed the per-library alias resolver — alias-form `extends` inside
+        //    a library (e.g. ai-openai's `extends: Ai.Model`) resolves against THAT
+        //    library's own `Telo.Import` declarations, not the root manifest's. Without
+        //    forwarding the imports, importing such a library would surface a spurious
+        //    EXTENDS_MALFORMED for an alias the library legitimately uses internally.
+        // Alias resolution itself stays in the analyzer; the loader's only semantic
+        // action is stamping `resolvedModuleName` / `resolvedNamespace` — recording the
+        // result of loading. Identity is cached per URL (see libraryIdentityByUrl above)
+        // because the same library can be reached through multiple chains, and every
+        // Telo.Import doc — including the duplicates short-circuited by `visited` —
+        // must end up stamped, otherwise per-scope alias resolution falls back to a
+        // path-derived string (e.g. "abstract-lib.yaml") and produces wrong canonical
+        // kinds.
         const importedDefs = [];
         const queue = [...entry];
         while (queue.length > 0) {
@@ -291,36 +314,52 @@ export class Loader {
             const importUrl = importSource.startsWith(".") || importSource.startsWith("/")
                 ? this.pick(base).resolveRelative(base, importSource)
                 : importSource;
-            if (visited.has(importUrl))
-                continue;
-            visited.add(importUrl);
-            let imported;
-            try {
-                imported = await this.loadModule(importUrl);
-            }
-            catch (err) {
-                const e = err instanceof Error ? err : new Error(String(err));
-                e.sourceLine = m.metadata?.sourceLine ?? 0;
-                throw e;
-            }
-            // Import target must be a Telo.Library. Check the Library branch
-            // explicitly rather than "anything that's a module kind" so that a
-            // future third kind can't silently slip past as a valid import target.
-            const importedLibrary = imported.find((im) => im.kind === "Telo.Library");
-            const importedApplication = imported.find((im) => im.kind === "Telo.Application");
-            if (importedApplication) {
-                const e = new Error(`Telo.Import target '${importSource}' is a Telo.Application. ` +
-                    `Only Telo.Library modules may be imported. Applications are run directly, not imported.`);
-                e.sourceLine = m.metadata?.sourceLine ?? 0;
-                throw e;
+            if (!visited.has(importUrl)) {
+                visited.add(importUrl);
+                let imported;
+                try {
+                    imported = await this.loadModule(importUrl);
+                }
+                catch (err) {
+                    const e = err instanceof Error ? err : new Error(String(err));
+                    e.sourceLine = m.metadata?.sourceLine ?? 0;
+                    throw e;
+                }
+                // Import target must be a Telo.Library. Check the Library branch
+                // explicitly rather than "anything that's a module kind" so that a
+                // future third kind can't silently slip past as a valid import target.
+                const importedLibrary = imported.find((im) => im.kind === "Telo.Library");
+                const importedApplication = imported.find((im) => im.kind === "Telo.Application");
+                if (importedApplication) {
+                    const e = new Error(`Telo.Import target '${importSource}' is a Telo.Application. ` +
+                        `Only Telo.Library modules may be imported. Applications are run directly, not imported.`);
+                    e.sourceLine = m.metadata?.sourceLine ?? 0;
+                    throw e;
+                }
+                if (importedLibrary?.metadata?.name) {
+                    libraryIdentityByUrl.set(importUrl, {
+                        name: importedLibrary.metadata.name,
+                        namespace: importedLibrary.metadata.namespace ?? null,
+                    });
+                }
+                for (const im of imported) {
+                    if (im.kind === "Telo.Definition" ||
+                        im.kind === "Telo.Abstract" ||
+                        im.kind === "Telo.Import") {
+                        importedDefs.push(im);
+                    }
+                    if (im.kind === "Telo.Import")
+                        queue.push(im);
+                }
             }
-            const importedModule = importedLibrary;
-            if (importedModule?.metadata?.name) {
+            // Stamp m with cached identity (works for both fresh and duplicate visits).
+            const identity = libraryIdentityByUrl.get(importUrl);
+            if (identity) {
                 const pi = m.metadata?.positionIndex;
                 m.metadata = {
                     ...m.metadata,
-                    resolvedModuleName: importedModule.metadata.name,
-                    resolvedNamespace: importedModule.metadata.namespace ?? null,
+                    resolvedModuleName: identity.name,
+                    resolvedNamespace: identity.namespace,
                 };
                 if (pi) {
                     Object.defineProperty(m.metadata, "positionIndex", {
@@ -331,12 +370,6 @@ export class Loader {
                     });
                 }
             }
-            for (const im of imported) {
-                if (im.kind === "Telo.Definition")
-                    importedDefs.push(im);
-                if (im.kind === "Telo.Import")
-                    queue.push(im);
-            }
         }
         return [...entry, ...importedDefs];
     }

package/dist/validate-extends.d.ts

@@ -0,0 +1,26 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Phase 3b — Validate `extends` fields on Telo.Definition docs, and flag the legacy
+ * `capability: <UserAbstract>` overload with CAPABILITY_SHADOWS_EXTENDS so users migrate.
+ *
+ * `extends` uses alias form ("<Alias>.<Name>") resolved against the declaring file's
+ * Telo.Import declarations — same pattern as `kind:` prefixes. The analyzer pre-resolves
+ * via AliasResolver before register() is called, so by the time this validator runs,
+ * the definition's effective `extends` is either the canonical form (when the alias was
+ * known) or the original alias-prefixed string (when it wasn't).
+ *
+ * Diagnostics:
+ *  - EXTENDS_MALFORMED: value not in "<Alias>.<Name>" alias form, or not resolvable
+ *    via the declaring file's imports (alias unknown → can't distinguish from a typo).
+ *  - EXTENDS_UNKNOWN_TARGET: alias resolves to a module, but that module has no
+ *    registered definition with the target name.
+ *  - EXTENDS_NON_ABSTRACT: target resolves to a Telo.Definition, not a Telo.Abstract.
+ *  - CAPABILITY_SHADOWS_EXTENDS (warning): `capability` names a user-declared abstract
+ *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
+ *    never trigger this — they're lifecycle roles by design.
+ */
+export declare function validateExtends(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-extends.d.ts.map

package/dist/validate-extends.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-extends.d.ts","sourceRoot":"","sources":["../src/validate-extends.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAOzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CA4ItB"}

package/dist/validate-extends.js

@@ -0,0 +1,163 @@
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/** Alias-form pattern for `extends`: "<Alias>.<AbstractName>", two PascalCase segments. */
+const EXTENDS_ALIAS_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
+/**
+ * Phase 3b — Validate `extends` fields on Telo.Definition docs, and flag the legacy
+ * `capability: <UserAbstract>` overload with CAPABILITY_SHADOWS_EXTENDS so users migrate.
+ *
+ * `extends` uses alias form ("<Alias>.<Name>") resolved against the declaring file's
+ * Telo.Import declarations — same pattern as `kind:` prefixes. The analyzer pre-resolves
+ * via AliasResolver before register() is called, so by the time this validator runs,
+ * the definition's effective `extends` is either the canonical form (when the alias was
+ * known) or the original alias-prefixed string (when it wasn't).
+ *
+ * Diagnostics:
+ *  - EXTENDS_MALFORMED: value not in "<Alias>.<Name>" alias form, or not resolvable
+ *    via the declaring file's imports (alias unknown → can't distinguish from a typo).
+ *  - EXTENDS_UNKNOWN_TARGET: alias resolves to a module, but that module has no
+ *    registered definition with the target name.
+ *  - EXTENDS_NON_ABSTRACT: target resolves to a Telo.Definition, not a Telo.Abstract.
+ *  - CAPABILITY_SHADOWS_EXTENDS (warning): `capability` names a user-declared abstract
+ *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
+ *    never trigger this — they're lifecycle roles by design.
+ */
+export function validateExtends(manifests, registry, aliases) {
+    const diagnostics = [];
+    // Defs forwarded from imported libraries carry `metadata.module` set to that
+    // library's name (stamped by the loader). The analyzer's Phase 1 already normalized
+    // their `extends` against the declaring library's own alias scope (`aliasesByModule`
+    // in analyzer.ts), so the canonical-form value is correct. What this validator can't
+    // re-check is whether the original alias was well-formed in the library's source —
+    // that's the library author's concern, surfaced when the library is analyzed as a
+    // root. Re-validating here against the consumer's alias scope (which doesn't know
+    // the library's internal aliases) would produce false-positive EXTENDS_MALFORMED /
+    // EXTENDS_UNKNOWN_TARGET. Skip forwarded defs entirely.
+    const importedModules = new Set();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const resolved = m.metadata?.resolvedModuleName;
+        if (resolved)
+            importedModules.add(resolved);
+    }
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const name = m.metadata?.name;
+        if (!name)
+            continue;
+        const ownModule = m.metadata?.module;
+        if (ownModule && importedModules.has(ownModule))
+            continue;
+        const filePath = m.metadata?.source;
+        const resource = { kind: m.kind, name };
+        const label = `${m.kind}/${name}`;
+        // --- extends validation ---
+        // At this point `m.extends` is whatever the manifest declared (alias form, e.g.
+        // "Ai.Model"). Resolve through the AliasResolver to the canonical form before
+        // looking up the target definition.
+        const extendsValue = m.extends;
+        if (extendsValue !== undefined) {
+            if (typeof extendsValue !== "string") {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "EXTENDS_MALFORMED",
+                    source: SOURCE,
+                    message: `${label}: 'extends' must be a string in alias form "<Alias>.<Name>"`,
+                    data: { resource, filePath, path: "extends" },
+                });
+            }
+            else if (!EXTENDS_ALIAS_RE.test(extendsValue)) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "EXTENDS_MALFORMED",
+                    source: SOURCE,
+                    message: `${label}: 'extends: ${extendsValue}' must be in alias form "<Alias>.<Name>" ` +
+                        `(e.g. "Ai.Model"), resolved via this file's Telo.Import declarations.`,
+                    data: { resource, filePath, path: "extends" },
+                });
+            }
+            else {
+                const prefix = extendsValue.slice(0, extendsValue.indexOf("."));
+                if (!aliases.hasAlias(prefix)) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "EXTENDS_MALFORMED",
+                        source: SOURCE,
+                        message: `${label}: 'extends: ${extendsValue}' — alias '${prefix}' is not a Telo.Import ` +
+                            `in this file's scope. Declare the import or correct the alias.`,
+                        data: { resource, filePath, path: "extends" },
+                    });
+                }
+                else {
+                    const canonical = aliases.resolveKind(extendsValue);
+                    if (!canonical) {
+                        // Alias exists but the suffix isn't in its exported kinds — behave like
+                        // an unknown target so users see the symbol is wrong, not that the alias is.
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "EXTENDS_UNKNOWN_TARGET",
+                            source: SOURCE,
+                            message: `${label}: 'extends' target '${extendsValue}' is not an exported kind of alias '${prefix}'.`,
+                            data: { resource, filePath, path: "extends" },
+                        });
+                    }
+                    else {
+                        const targetDef = registry.resolve(canonical);
+                        if (!targetDef) {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "EXTENDS_UNKNOWN_TARGET",
+                                source: SOURCE,
+                                message: `${label}: 'extends' target '${extendsValue}' (resolved: '${canonical}') is not a registered definition.`,
+                                data: { resource, filePath, path: "extends" },
+                            });
+                        }
+                        else if (targetDef.kind !== "Telo.Abstract") {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "EXTENDS_NON_ABSTRACT",
+                                source: SOURCE,
+                                message: `${label}: 'extends' target '${extendsValue}' (resolved: '${canonical}') is a ${targetDef.kind}, not a Telo.Abstract. ` +
+                                    `Only Telo.Abstract declarations may be extended.`,
+                                data: { resource, filePath, path: "extends" },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // --- legacy capability-as-abstract warning ---
+        // `capability` is expected to name either a builtin lifecycle (module "Telo") or a
+        // user-declared abstract. The latter is the pre-`extends` overload — emit a warning
+        // suggesting the canonical form. Resolve through aliases first because the manifest
+        // retains the alias-prefixed form (e.g. "AbstractLib.Greeter"); the registered key
+        // is the canonical form after alias resolution (e.g. "abstract-lib.Greeter").
+        const capability = m.capability;
+        if (typeof capability === "string") {
+            const resolvedCap = aliases.resolveKind(capability) ?? capability;
+            const capDef = registry.resolve(resolvedCap);
+            if (capDef &&
+                capDef.kind === "Telo.Abstract" &&
+                capDef.metadata.module !== "Telo") {
+                // Build suggestion using the original alias form if aliases can produce it.
+                const aliasesForModule = aliases.aliasesFor(capDef.metadata.module);
+                const suggestion = aliasesForModule.length > 0
+                    ? `${aliasesForModule[0]}.${capDef.metadata.name}`
+                    : `${capDef.metadata.module}.${capDef.metadata.name}`;
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Warning,
+                    code: "CAPABILITY_SHADOWS_EXTENDS",
+                    source: SOURCE,
+                    message: `${label}: 'capability: ${capability}' names a user-declared abstract. ` +
+                        `Prefer 'extends' for implements-this-abstract declarations; 'capability' should ` +
+                        `name a lifecycle role. Use \`extends: "${suggestion}"\` with a lifecycle ` +
+                        `\`capability\` (e.g. Telo.Invocable, Telo.Provider, Telo.Service).`,
+                    data: { resource, filePath, path: "capability" },
+                });
+            }
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,7 +41,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/sdk": "0.3.2"
+    "@telorun/sdk": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analyzer.ts

@@ -28,6 +28,7 @@ import {
   resolveTypeFieldToSchema,
   validateChainAgainstSchema,
 } from "./validate-cel-context.js";
+import { validateExtends } from "./validate-extends.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
@@ -293,9 +294,24 @@ export class StaticAnalyzer {
     // Register module identities and aliases.
     // The root module doc (Telo.Application or Telo.Library) provides its own
     // identity; imported modules surface their identity via resolvedModuleName/
-    // resolvedNamespace stamped onto the Telo.Import by the loader (so we don't
-    // need to include imported module manifests in the analysis set, avoiding false
-    // reference errors in the parent context).
+    // resolvedNamespace stamped onto the Telo.Import by the loader.
+    //
+    // Two alias scopes are tracked:
+    //  - `aliases` — the consumer's aliases, populated from Telo.Imports declared in
+    //    the entry manifest (its own module).
+    //  - `aliasesByModule` — per-imported-library aliases, populated from Telo.Imports
+    //    forwarded by the loader from inside imported libraries. A library may use
+    //    different alias names than the consumer for the same dependency; resolving
+    //    a forwarded def's `extends` / `capability` against the consumer's scope
+    //    would either fail or pick the wrong target. Each forwarded def is normalized
+    //    in its own library's scope.
+    const rootModules = new Set<string>();
+    for (const m of manifests) {
+      if (isModuleKind(m.kind) && m.metadata?.name) {
+        rootModules.add(m.metadata.name as string);
+      }
+    }
+    const aliasesByModule = new Map<string, AliasResolver>();
     for (const m of manifests) {
       if (isModuleKind(m.kind)) {
         const namespace = ((m.metadata as any).namespace as string | undefined) ?? null;
@@ -311,30 +327,60 @@ export class StaticAnalyzer {
           | string
           | null
           | undefined;
+        const ownModule = (m.metadata as { module?: string } | undefined)?.module;
         if (alias && source) {
           const targetModule =
             resolvedModuleName ?? source.split("/").filter(Boolean).pop() ?? source;
-          aliases.registerImport(alias, targetModule, exportedKinds);
+          // Module identity is registered globally so x-telo-ref resolution sees
+          // transitively-imported modules regardless of which scope brought them in.
           if (resolvedModuleName) {
             defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
           }
+          // Alias registration is scoped: consumer imports vs. imported-library imports.
+          if (!ownModule || rootModules.has(ownModule)) {
+            aliases.registerImport(alias, targetModule, exportedKinds);
+          } else {
+            let libResolver = aliasesByModule.get(ownModule);
+            if (!libResolver) {
+              libResolver = new AliasResolver();
+              aliasesByModule.set(ownModule, libResolver);
+            }
+            libResolver.registerImport(alias, targetModule, exportedKinds);
+          }
         }
       }
     }
 
-    // Register definitions from Telo.Definition resources.
-    // Normalize alias-prefixed `capability` to canonical form so extendedBy lookup works
-    // (e.g. "Workflow.Backend" → "workflow.Backend" when "Workflow" is a known alias).
+    // Register definitions from Telo.Definition AND Telo.Abstract resources.
+    // Abstracts declare contracts that implementations target via `extends` (canonical)
+    // or `capability: <AbstractKind>` (legacy). Until they're registered, validateReferences
+    // can't resolve x-telo-ref entries pointing at library-declared abstracts — so abstracts
+    // must go through register() too, not just the kernel builtins in the constructor.
+    //
+    // Normalize alias-prefixed `capability` and `extends` to canonical form using the
+    // declaring scope's resolver, so `extendedBy` is keyed by canonical kind regardless
+    // of alias choices. `capability` covers the legacy implements-this-abstract overload;
+    // `extends` is the canonical first-class form.
     for (const m of manifests) {
-      if (m.kind === "Telo.Definition") {
-        const def = m as unknown as ResourceDefinition;
-        const resolvedCapability = def.capability
-          ? (aliases.resolveKind(def.capability) ?? def.capability)
-          : def.capability;
-        defs.register(
-          resolvedCapability !== def.capability ? { ...def, capability: resolvedCapability } : def,
-        );
-      }
+      if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
+      const def = m as unknown as ResourceDefinition;
+      const ownModule = (def.metadata as { module?: string } | undefined)?.module;
+      const scopeResolver =
+        ownModule && !rootModules.has(ownModule)
+          ? (aliasesByModule.get(ownModule) ?? new AliasResolver())
+          : aliases;
+      const resolvedCapability = def.capability
+        ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
+        : def.capability;
+      const resolvedExtends = def.extends
+        ? (scopeResolver.resolveKind(def.extends) ?? def.extends)
+        : def.extends;
+      const needsPatch =
+        resolvedCapability !== def.capability || resolvedExtends !== def.extends;
+      const normalized = needsPatch
+        ? { ...def, capability: resolvedCapability, extends: resolvedExtends }
+        : def;
+      defs.register(normalized);
     }
 
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
@@ -520,6 +566,9 @@ export class StaticAnalyzer {
     // Validate resource references (Phase 3)
     diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs }));
 
+    // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
+    diagnostics.push(...validateExtends(allManifests, defs, aliases));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 

package/src/builtins.ts

@@ -27,9 +27,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           additionalProperties: true,
         },
         capability: { type: "string" },
+        schema: { type: "object", additionalProperties: true },
       },
       required: ["metadata"],
-      additionalProperties: false,
+      // Telo.Abstract is an extension point by design — it must accept forward-compatible
+      // fields (e.g. inputType/outputType from the typed-abstracts plan) without requiring
+      // the analyzer to enumerate them here.
+      additionalProperties: true,
     },
   },
   {
@@ -55,6 +59,12 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         source: { type: "string" },
         variables: { type: "object" },
         secrets: { type: "object" },
+        runtime: {
+          oneOf: [
+            { type: "string" },
+            { type: "array", items: { type: "string" } },
+          ],
+        },
       },
       required: ["metadata", "source"],
       additionalProperties: false,

package/src/definition-registry.ts

@@ -32,13 +32,22 @@ export class DefinitionRegistry {
     const key = mod ? `${mod}.${name}` : name;
     this.defs.set(key, definition);
     this.fieldMaps.set(key, buildReferenceFieldMap(definition.schema ?? {}));
+    // `capability` populates extendedBy for backward-compat with the legacy pattern where
+    // a concrete definition overloaded `capability: <AbstractKind>` to mean "implements
+    // this abstract." The canonical pattern is `extends` (below). Both populate the index,
+    // unioned — so in-flight modules pre-migration keep working.
     if (definition.capability) {
-      const children = this.extendedBy.get(definition.capability);
-      if (children) {
-        children.push(key);
-      } else {
-        this.extendedBy.set(definition.capability, [key]);
-      }
+      this.addExtendedBy(definition.capability, key);
+    }
+    // `extends` — first-class "implements-this-abstract" edge. Alias-form resolution
+    // happens in the analyzer before register() is called (analyzer.ts pre-resolves
+    // via aliases.resolveKind), so the value here is already the canonical kind string
+    // (e.g. "workflow.Backend"). If the analyzer could not resolve the alias (partial
+    // context, or the declaring file doesn't import the target's alias), the value
+    // stays as the original alias-prefixed form; validateExtends emits EXTENDS_MALFORMED
+    // or EXTENDS_UNKNOWN_TARGET depending on the case.
+    if (definition.extends) {
+      this.addExtendedBy(definition.extends, key);
     }
     // Auto-register the telo identity when any Telo built-in is registered.
     if (definition.kind === "Telo.Abstract" && mod === "Telo") {
@@ -51,6 +60,15 @@ export class DefinitionRegistry {
     }
   }
 
+  private addExtendedBy(parent: string, child: string): void {
+    const children = this.extendedBy.get(parent);
+    if (children) {
+      if (!children.includes(child)) children.push(child);
+    } else {
+      this.extendedBy.set(parent, [child]);
+    }
+  }
+
   /** Register a module identity for x-telo-ref resolution.
    *  Call once per module doc (Telo.Application or Telo.Library) when the manifest is loaded.
    *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.

package/src/manifest-loader.ts

@@ -333,8 +333,34 @@ export class Loader {
 
   async loadManifests(entryUrl: string): Promise<ResourceManifest[]> {
     const visited = new Set<string>([entryUrl]);
+    // Cache resolved library identity per import URL so a Telo.Import re-encountered
+    // through a different chain still gets `resolvedModuleName` / `resolvedNamespace`
+    // stamped — without re-loading the target. The early `visited` short-circuit used
+    // to silently leave duplicate Telo.Imports unstamped, which broke alias resolution
+    // when the same library was imported by two different files in the same analysis set.
+    const libraryIdentityByUrl = new Map<
+      string,
+      { name: string; namespace: string | null }
+    >();
     const entry = await this.loadModule(entryUrl);
 
+    // Forward Telo.Definition, Telo.Abstract, AND Telo.Import docs from imported
+    // libraries to the analyzer so its downstream passes can see them:
+    //  - Definitions / Abstracts feed cross-package `x-telo-ref` resolution and
+    //    `extends` target validation.
+    //  - Imports feed the per-library alias resolver — alias-form `extends` inside
+    //    a library (e.g. ai-openai's `extends: Ai.Model`) resolves against THAT
+    //    library's own `Telo.Import` declarations, not the root manifest's. Without
+    //    forwarding the imports, importing such a library would surface a spurious
+    //    EXTENDS_MALFORMED for an alias the library legitimately uses internally.
+    // Alias resolution itself stays in the analyzer; the loader's only semantic
+    // action is stamping `resolvedModuleName` / `resolvedNamespace` — recording the
+    // result of loading. Identity is cached per URL (see libraryIdentityByUrl above)
+    // because the same library can be reached through multiple chains, and every
+    // Telo.Import doc — including the duplicates short-circuited by `visited` —
+    // must end up stamped, otherwise per-scope alias resolution falls back to a
+    // path-derived string (e.g. "abstract-lib.yaml") and produces wrong canonical
+    // kinds.
     const importedDefs: ResourceManifest[] = [];
     const queue: ResourceManifest[] = [...entry];
 
@@ -348,36 +374,56 @@ export class Loader {
         importSource.startsWith(".") || importSource.startsWith("/")
           ? this.pick(base).resolveRelative(base, importSource)
           : importSource;
-      if (visited.has(importUrl)) continue;
-      visited.add(importUrl);
-      let imported: ResourceManifest[];
-      try {
-        imported = await this.loadModule(importUrl);
-      } catch (err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
-        throw e;
-      }
-      // Import target must be a Telo.Library. Check the Library branch
-      // explicitly rather than "anything that's a module kind" so that a
-      // future third kind can't silently slip past as a valid import target.
-      const importedLibrary = imported.find((im) => im.kind === "Telo.Library");
-      const importedApplication = imported.find((im) => im.kind === "Telo.Application");
-      if (importedApplication) {
-        const e = new Error(
-          `Telo.Import target '${importSource}' is a Telo.Application. ` +
-            `Only Telo.Library modules may be imported. Applications are run directly, not imported.`,
-        );
-        (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
-        throw e;
+
+      if (!visited.has(importUrl)) {
+        visited.add(importUrl);
+        let imported: ResourceManifest[];
+        try {
+          imported = await this.loadModule(importUrl);
+        } catch (err) {
+          const e = err instanceof Error ? err : new Error(String(err));
+          (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
+          throw e;
+        }
+        // Import target must be a Telo.Library. Check the Library branch
+        // explicitly rather than "anything that's a module kind" so that a
+        // future third kind can't silently slip past as a valid import target.
+        const importedLibrary = imported.find((im) => im.kind === "Telo.Library");
+        const importedApplication = imported.find((im) => im.kind === "Telo.Application");
+        if (importedApplication) {
+          const e = new Error(
+            `Telo.Import target '${importSource}' is a Telo.Application. ` +
+              `Only Telo.Library modules may be imported. Applications are run directly, not imported.`,
+          );
+          (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
+          throw e;
+        }
+        if (importedLibrary?.metadata?.name) {
+          libraryIdentityByUrl.set(importUrl, {
+            name: importedLibrary.metadata.name as string,
+            namespace: ((importedLibrary.metadata as any).namespace as string | null) ?? null,
+          });
+        }
+        for (const im of imported) {
+          if (
+            im.kind === "Telo.Definition" ||
+            im.kind === "Telo.Abstract" ||
+            im.kind === "Telo.Import"
+          ) {
+            importedDefs.push(im);
+          }
+          if (im.kind === "Telo.Import") queue.push(im);
+        }
       }
-      const importedModule = importedLibrary;
-      if (importedModule?.metadata?.name) {
+
+      // Stamp m with cached identity (works for both fresh and duplicate visits).
+      const identity = libraryIdentityByUrl.get(importUrl);
+      if (identity) {
         const pi = (m.metadata as any)?.positionIndex;
         m.metadata = {
           ...m.metadata,
-          resolvedModuleName: importedModule.metadata.name as string,
-          resolvedNamespace: (importedModule.metadata as any).namespace ?? null,
+          resolvedModuleName: identity.name,
+          resolvedNamespace: identity.namespace,
         };
         if (pi) {
           Object.defineProperty(m.metadata, "positionIndex", {
@@ -388,10 +434,6 @@ export class Loader {
           });
         }
       }
-      for (const im of imported) {
-        if (im.kind === "Telo.Definition") importedDefs.push(im);
-        if (im.kind === "Telo.Import") queue.push(im);
-      }
     }
 
     return [...entry, ...importedDefs];

package/src/validate-extends.ts

@@ -0,0 +1,175 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** Alias-form pattern for `extends`: "<Alias>.<AbstractName>", two PascalCase segments. */
+const EXTENDS_ALIAS_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
+
+/**
+ * Phase 3b — Validate `extends` fields on Telo.Definition docs, and flag the legacy
+ * `capability: <UserAbstract>` overload with CAPABILITY_SHADOWS_EXTENDS so users migrate.
+ *
+ * `extends` uses alias form ("<Alias>.<Name>") resolved against the declaring file's
+ * Telo.Import declarations — same pattern as `kind:` prefixes. The analyzer pre-resolves
+ * via AliasResolver before register() is called, so by the time this validator runs,
+ * the definition's effective `extends` is either the canonical form (when the alias was
+ * known) or the original alias-prefixed string (when it wasn't).
+ *
+ * Diagnostics:
+ *  - EXTENDS_MALFORMED: value not in "<Alias>.<Name>" alias form, or not resolvable
+ *    via the declaring file's imports (alias unknown → can't distinguish from a typo).
+ *  - EXTENDS_UNKNOWN_TARGET: alias resolves to a module, but that module has no
+ *    registered definition with the target name.
+ *  - EXTENDS_NON_ABSTRACT: target resolves to a Telo.Definition, not a Telo.Abstract.
+ *  - CAPABILITY_SHADOWS_EXTENDS (warning): `capability` names a user-declared abstract
+ *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
+ *    never trigger this — they're lifecycle roles by design.
+ */
+export function validateExtends(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  // Defs forwarded from imported libraries carry `metadata.module` set to that
+  // library's name (stamped by the loader). The analyzer's Phase 1 already normalized
+  // their `extends` against the declaring library's own alias scope (`aliasesByModule`
+  // in analyzer.ts), so the canonical-form value is correct. What this validator can't
+  // re-check is whether the original alias was well-formed in the library's source —
+  // that's the library author's concern, surfaced when the library is analyzed as a
+  // root. Re-validating here against the consumer's alias scope (which doesn't know
+  // the library's internal aliases) would produce false-positive EXTENDS_MALFORMED /
+  // EXTENDS_UNKNOWN_TARGET. Skip forwarded defs entirely.
+  const importedModules = new Set<string>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const resolved = (m.metadata as { resolvedModuleName?: string } | undefined)?.resolvedModuleName;
+    if (resolved) importedModules.add(resolved);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const name = m.metadata?.name as string | undefined;
+    if (!name) continue;
+    const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+    if (ownModule && importedModules.has(ownModule)) continue;
+    const filePath = (m.metadata as { source?: string } | undefined)?.source;
+    const resource = { kind: m.kind, name };
+    const label = `${m.kind}/${name}`;
+
+    // --- extends validation ---
+    // At this point `m.extends` is whatever the manifest declared (alias form, e.g.
+    // "Ai.Model"). Resolve through the AliasResolver to the canonical form before
+    // looking up the target definition.
+    const extendsValue = (m as { extends?: unknown }).extends;
+    if (extendsValue !== undefined) {
+      if (typeof extendsValue !== "string") {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "EXTENDS_MALFORMED",
+          source: SOURCE,
+          message: `${label}: 'extends' must be a string in alias form "<Alias>.<Name>"`,
+          data: { resource, filePath, path: "extends" },
+        });
+      } else if (!EXTENDS_ALIAS_RE.test(extendsValue)) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "EXTENDS_MALFORMED",
+          source: SOURCE,
+          message:
+            `${label}: 'extends: ${extendsValue}' must be in alias form "<Alias>.<Name>" ` +
+            `(e.g. "Ai.Model"), resolved via this file's Telo.Import declarations.`,
+          data: { resource, filePath, path: "extends" },
+        });
+      } else {
+        const prefix = extendsValue.slice(0, extendsValue.indexOf("."));
+        if (!aliases.hasAlias(prefix)) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "EXTENDS_MALFORMED",
+            source: SOURCE,
+            message:
+              `${label}: 'extends: ${extendsValue}' — alias '${prefix}' is not a Telo.Import ` +
+              `in this file's scope. Declare the import or correct the alias.`,
+            data: { resource, filePath, path: "extends" },
+          });
+        } else {
+          const canonical = aliases.resolveKind(extendsValue);
+          if (!canonical) {
+            // Alias exists but the suffix isn't in its exported kinds — behave like
+            // an unknown target so users see the symbol is wrong, not that the alias is.
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "EXTENDS_UNKNOWN_TARGET",
+              source: SOURCE,
+              message: `${label}: 'extends' target '${extendsValue}' is not an exported kind of alias '${prefix}'.`,
+              data: { resource, filePath, path: "extends" },
+            });
+          } else {
+            const targetDef = registry.resolve(canonical);
+            if (!targetDef) {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "EXTENDS_UNKNOWN_TARGET",
+                source: SOURCE,
+                message: `${label}: 'extends' target '${extendsValue}' (resolved: '${canonical}') is not a registered definition.`,
+                data: { resource, filePath, path: "extends" },
+              });
+            } else if (targetDef.kind !== "Telo.Abstract") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "EXTENDS_NON_ABSTRACT",
+                source: SOURCE,
+                message:
+                  `${label}: 'extends' target '${extendsValue}' (resolved: '${canonical}') is a ${targetDef.kind}, not a Telo.Abstract. ` +
+                  `Only Telo.Abstract declarations may be extended.`,
+                data: { resource, filePath, path: "extends" },
+              });
+            }
+          }
+        }
+      }
+    }
+
+    // --- legacy capability-as-abstract warning ---
+    // `capability` is expected to name either a builtin lifecycle (module "Telo") or a
+    // user-declared abstract. The latter is the pre-`extends` overload — emit a warning
+    // suggesting the canonical form. Resolve through aliases first because the manifest
+    // retains the alias-prefixed form (e.g. "AbstractLib.Greeter"); the registered key
+    // is the canonical form after alias resolution (e.g. "abstract-lib.Greeter").
+    const capability = (m as { capability?: unknown }).capability;
+    if (typeof capability === "string") {
+      const resolvedCap = aliases.resolveKind(capability) ?? capability;
+      const capDef = registry.resolve(resolvedCap);
+      if (
+        capDef &&
+        capDef.kind === "Telo.Abstract" &&
+        capDef.metadata.module !== "Telo"
+      ) {
+        // Build suggestion using the original alias form if aliases can produce it.
+        const aliasesForModule = aliases.aliasesFor(capDef.metadata.module);
+        const suggestion =
+          aliasesForModule.length > 0
+            ? `${aliasesForModule[0]}.${capDef.metadata.name}`
+            : `${capDef.metadata.module}.${capDef.metadata.name}`;
+        diagnostics.push({
+          severity: DiagnosticSeverity.Warning,
+          code: "CAPABILITY_SHADOWS_EXTENDS",
+          source: SOURCE,
+          message:
+            `${label}: 'capability: ${capability}' names a user-declared abstract. ` +
+            `Prefer 'extends' for implements-this-abstract declarations; 'capability' should ` +
+            `name a lifecycle role. Use \`extends: "${suggestion}"\` with a lifecycle ` +
+            `\`capability\` (e.g. Telo.Invocable, Telo.Provider, Telo.Service).`,
+          data: { resource, filePath, path: "capability" },
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}