@telorun/analyzer 0.3.0 → 0.5.0

package/dist/types.d.ts

@@ -35,7 +35,7 @@ export interface AnalysisDiagnostic {
     /** Telo-specific extras such as { resource: { kind, name }, path } */
     data?: unknown;
 }
-export interface ManifestAdapter {
+export interface ManifestSource {
     supports(url: string): boolean;
     read(url: string): Promise<{
         text: string;
@@ -44,11 +44,11 @@ export interface ManifestAdapter {
     resolveRelative(base: string, relative: string): string;
     /** Expand glob patterns relative to a base source. Returns sources in the same
      *  format as read().source — suitable to pass back into read() / resolveRelative().
-     *  Optional — only filesystem-capable adapters implement this. */
+     *  Optional — only filesystem-capable sources implement this. */
     expandGlob?(base: string, patterns: string[]): Promise<string[]>;
     /** Walk parent directories from fileUrl looking for the nearest telo.yaml.
      *  Returns the source in the same format as read().source, or null if none found.
-     *  Optional — only filesystem-capable adapters implement this. */
+     *  Optional — only filesystem-capable sources implement this. */
     resolveOwnerOf?(fileUrl: string): Promise<string | null>;
 }
 export interface LoadOptions {
@@ -59,13 +59,13 @@ export interface LoadOptions {
     compile?: boolean;
 }
 export interface LoaderInitOptions {
-    /** Adapters inserted with highest priority before built-ins. */
-    extraAdapters?: ManifestAdapter[];
-    /** Include built-in HttpAdapter. Defaults to true. */
-    includeHttpAdapter?: boolean;
-    /** Include built-in RegistryAdapter. Defaults to true. */
-    includeRegistryAdapter?: boolean;
-    /** Base URL used by built-in RegistryAdapter when enabled. */
+    /** Sources inserted with highest priority before built-ins. */
+    extraSources?: ManifestSource[];
+    /** Include built-in HttpSource. Defaults to true. */
+    includeHttpSource?: boolean;
+    /** Include built-in RegistrySource. Defaults to true. */
+    includeRegistrySource?: boolean;
+    /** Base URL used by built-in RegistrySource when enabled. */
     registryUrl?: string;
     /** Handlers for CEL stdlib functions (e.g. `sha256`). Analyzer-only callers may
      *  omit this and get throwing stubs; runtime callers (kernel) must supply real impls. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;sEAEkE;IAClE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;sEAEkE;IAClE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CACrE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;qEAEiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;qEAEiE;IACjE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CACrE"}

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.5.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.6.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/index.ts

@@ -1,14 +1,17 @@
-export { HttpAdapter } from "./adapters/http-adapter.js";
-export { RegistryAdapter } from "./adapters/registry-adapter.js";
 export { AnalysisRegistry } from "./analysis-registry.js";
 export { StaticAnalyzer } from "./analyzer.js";
 export { Loader } from "./manifest-loader.js";
-export { MODULE_KINDS, isModuleKind } from "./module-kinds.js";
+export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
+export { HttpSource } from "./sources/http-source.js";
+export { RegistrySource } from "./sources/registry-source.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,
-    AnalysisOptions, LoaderInitOptions, LoadOptions, ManifestAdapter,
+    AnalysisOptions,
+    LoaderInitOptions,
+    LoadOptions,
+    ManifestSource,
     Position,
     PositionIndex,
     Range