@telorun/analyzer 0.11.0 → 0.12.1

package/LICENSE

@@ -1,6 +1,6 @@
 # SUSTAINABLE USE LICENSE (Fair-code)
 
-Copyright (c) 2026 DiglyAI
+Copyright (c) 2026 CodeNet Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
 
@@ -14,4 +14,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
 
-For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="./assets/telo.png" alt="Telo" width="200" />
+  <img src="https://raw.githubusercontent.com/telorun/telo/main/assets/telo.png" alt="Telo" width="200" />
 </p>
 
 <h1 align="center">Telo</h1>
@@ -61,12 +61,12 @@ targets:
 kind: Telo.Import
 metadata:
   name: Http
-source: ../modules/http-server
+source: std/http-server@0.5.0
 ---
 kind: Telo.Import
 metadata:
   name: Sql
-source: ../modules/sql
+source: std/sql@0.3.0
 ---
 # SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
 kind: Sql.Connection

package/dist/analysis-registry.d.ts

@@ -41,6 +41,13 @@ export declare class AnalysisRegistry {
     /** Returns the closest user-facing kind to `badKind`, or undefined when nothing
      *  is close enough (or multiple candidates tie). Case-sensitive. */
     suggestKind(badKind: string): string | undefined;
+    /** Returns every user-facing (alias-form) kind that satisfies the given
+     *  `x-telo-ref` constraint string (e.g. `"telo#Invocable"`, `"std/sql#Connection"`).
+     *  Resolution mirrors `validateReferences.checkKind`: abstract targets expand to
+     *  the set of definitions extending them; concrete targets yield just themselves.
+     *  Returns `undefined` when the ref can't be resolved (e.g. unregistered identity),
+     *  so callers can fall back to the unfiltered kind list. */
+    userFacingKindsForRef(xTeloRef: string): string[] | undefined;
     /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
     _context(): AnalysisContext;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}
+{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}

package/dist/analysis-registry.js

@@ -79,6 +79,44 @@ export class AnalysisRegistry {
     suggestKind(badKind) {
         return computeSuggestKind(badKind, this.aliases, this.defs);
     }
+    /** Returns every user-facing (alias-form) kind that satisfies the given
+     *  `x-telo-ref` constraint string (e.g. `"telo#Invocable"`, `"std/sql#Connection"`).
+     *  Resolution mirrors `validateReferences.checkKind`: abstract targets expand to
+     *  the set of definitions extending them; concrete targets yield just themselves.
+     *  Returns `undefined` when the ref can't be resolved (e.g. unregistered identity),
+     *  so callers can fall back to the unfiltered kind list. */
+    userFacingKindsForRef(xTeloRef) {
+        const targetKind = this.defs.resolveRef(xTeloRef);
+        if (!targetKind)
+            return undefined;
+        const targetDef = this.defs.resolve(targetKind);
+        if (!targetDef)
+            return undefined;
+        const canonicalKinds = [];
+        if (targetDef.kind === "Telo.Abstract") {
+            for (const def of this.defs.getByExtends(targetKind)) {
+                const module = def.metadata?.module;
+                if (module && def.metadata?.name) {
+                    canonicalKinds.push(`${module}.${def.metadata.name}`);
+                }
+            }
+        }
+        else {
+            canonicalKinds.push(targetKind);
+        }
+        const out = new Set();
+        for (const kind of canonicalKinds) {
+            const dot = kind.indexOf(".");
+            if (dot === -1)
+                continue;
+            const moduleName = kind.slice(0, dot);
+            const typeName = kind.slice(dot + 1);
+            for (const alias of this.aliases.aliasesFor(moduleName)) {
+                out.add(`${alias}.${typeName}`);
+            }
+        }
+        return Array.from(out);
+    }
     /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
     _context() {
         return { aliases: this.aliases, definitions: this.defs, aliasesByModule: this.aliasesByModule };

package/dist/analyzer.d.ts

@@ -8,6 +8,21 @@ export interface StaticAnalyzerOptions {
 export declare class StaticAnalyzer {
     private readonly celEnv;
     constructor(options?: StaticAnalyzerOptions);
+    /**
+     * Run static analysis over a flattened manifest list.
+     *
+     * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+     * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+     * `metadata.sourceLine` (number). The dedup that backs
+     * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+     * apart from a genuine collision, and downstream diagnostic positioning
+     * depends on them too. Real callers stamp positions already (the `Loader`,
+     * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+     * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+     * their inputs through `withSyntheticPositions(...)` before calling
+     * `analyze()`. A missing position throws a clear error rather than
+     * silently producing wrong diagnostics.
+     */
     analyze(manifests: ResourceManifest[], options?: AnalysisOptions, registry?: AnalysisRegistry): AnalysisDiagnostic[];
     analyzeErrors(manifests: ResourceManifest[], options?: AnalysisOptions, registry?: AnalysisRegistry): AnalysisDiagnostic[];
     normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[];

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;AAIzE,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;AA8c/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;IA6avB,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;IAUxF,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;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAif/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;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAoiBvB,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;IAexF,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;CAsB5F"}

package/dist/analyzer.js

@@ -7,13 +7,50 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
+import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
+import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
 import { getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.js";
 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 { validateThrowsCoverage } from "./validate-throws-coverage.js";
 const SELF_PREFIX = "Self.";
+/**
+ * `StaticAnalyzer.analyze()` requires `metadata.source` (non-empty) and
+ * `metadata.sourceLine` (number) on every non-system manifest — see the
+ * JSDoc on `analyze()`. Production callers stamp these via the `Loader` /
+ * `flattenForAnalyzer` / `emitDocsFor` paths; programmatic callers (tests,
+ * scripts) should pre-process inputs with `withSyntheticPositions(...)`.
+ * Surfacing the violation here turns silent dedup misbehaviour into a
+ * loud, actionable error.
+ */
+function assertManifestPositions(manifests) {
+    for (let i = 0; i < manifests.length; i++) {
+        const m = manifests[i];
+        if (REF_VALIDATION_SKIP_KINDS.has(m.kind))
+            continue;
+        const meta = m.metadata;
+        const okSource = typeof meta?.source === "string" && meta.source.length > 0;
+        const okLine = typeof meta?.sourceLine === "number";
+        if (okSource && okLine)
+            continue;
+        const label = `${m.kind}/${m.metadata?.name ?? "(unnamed)"}`;
+        const missing = [
+            !okSource ? "metadata.source" : null,
+            !okLine ? "metadata.sourceLine" : null,
+        ]
+            .filter(Boolean)
+            .join(" and ");
+        throw new Error(`StaticAnalyzer.analyze(): manifest #${i} (${label}) is missing ${missing}. ` +
+            `Real callers stamp positions automatically; programmatic callers ` +
+            `(tests, ad-hoc scripts) should pass inputs through ` +
+            `\`withSyntheticPositions(manifests)\` before calling analyze().`);
+    }
+}
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
  *  to its canonical form. `Self.<Name>` resolves to `<ownModule>.<Name>` —
  *  the magic alias for "this library's own module" — and other prefixes
@@ -373,7 +410,23 @@ export class StaticAnalyzer {
     constructor(options = {}) {
         this.celEnv = buildCelEnvironment(options.celHandlers);
     }
+    /**
+     * Run static analysis over a flattened manifest list.
+     *
+     * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+     * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+     * `metadata.sourceLine` (number). The dedup that backs
+     * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+     * apart from a genuine collision, and downstream diagnostic positioning
+     * depends on them too. Real callers stamp positions already (the `Loader`,
+     * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+     * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+     * their inputs through `withSyntheticPositions(...)` before calling
+     * `analyze()`. A missing position throws a clear error rather than
+     * silently producing wrong diagnostics.
+     */
     analyze(manifests, options, registry) {
+        assertManifestPositions(manifests);
         const diagnostics = [];
         // Use pre-seeded registries from the provided AnalysisRegistry, or create fresh ones.
         // New aliases/definitions found in the manifests are accumulated into the provided instance
@@ -490,6 +543,20 @@ export class StaticAnalyzer {
         }
         // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
         const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
+        // Phase 2.5: resolve `!ref <name>` sentinels at every ref slot to canonical
+        // {kind, name} objects so downstream phases (validation, dependency graph,
+        // kernel controllers) see a uniform shape. Runs after normalize so both
+        // original and inline-extracted manifests have their sentinels resolved.
+        resolveRefSentinels(allManifests, defs, aliases, aliasesByModule);
+        // Trusted-input fast path: when the caller has already attested that
+        // this exact manifest set passes analysis (e.g. via the kernel's
+        // hash-stamped `.validated.json` cache), skip the validation walk.
+        // Registration of identities / aliases / definitions and inline-resource
+        // normalisation have already run above; that's all downstream
+        // consumers (prepare, init loop) require.
+        if (options?.skipValidation) {
+            return diagnostics;
+        }
         // Build a name→manifest map for looking up referenced resources
         const byName = new Map();
         for (const m of allManifests) {
@@ -497,6 +564,64 @@ export class StaticAnalyzer {
                 byName.set(m.metadata.name, m);
             }
         }
+        // Fail loud on definition schemas AJV cannot compile. `validateAgainstSchema`
+        // and `validateWithRefs` swallow compile failures (returning no issues),
+        // which would silently skip schema validation for every resource of that
+        // kind — surface the broken schema once, anchored on the definition itself.
+        for (const m of allManifests) {
+            if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract")
+                continue;
+            const schema = m.schema;
+            if (!schema || typeof schema !== "object")
+                continue;
+            const name = m.metadata?.name;
+            if (!name)
+                continue;
+            const compileError = defs.schemaCompileError(schema);
+            if (compileError) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "SCHEMA_COMPILE_ERROR",
+                    source: SOURCE,
+                    message: `${m.kind}/${name}: definition schema failed to compile: ${compileError}`,
+                    data: {
+                        resource: { kind: m.kind, name },
+                        filePath: m.metadata?.source,
+                        path: "schema",
+                    },
+                });
+            }
+        }
+        // Library env: rejection — `env:` on a Library `variables` / `secrets`
+        // entry is forbidden. The Library entry schema is otherwise open so that
+        // any JSON Schema property schema is valid; this targeted check produces
+        // a clear diagnostic instead of a generic "additional property" error.
+        for (const m of allManifests) {
+            if (m.kind !== "Telo.Library")
+                continue;
+            const filePath = m.metadata?.source;
+            const moduleName = m.metadata?.name;
+            const resource = moduleName ? { kind: m.kind, name: moduleName } : undefined;
+            for (const block of ["variables", "secrets"]) {
+                const entries = m[block];
+                if (!entries || typeof entries !== "object" || Array.isArray(entries))
+                    continue;
+                for (const [entryName, entry] of Object.entries(entries)) {
+                    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                        continue;
+                    if ("env" in entry) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "LIBRARY_ENV_KEY_REJECTED",
+                            source: SOURCE,
+                            message: `Telo.Library ${block}/${entryName}: 'env:' is only permitted on Telo.Application entries. ` +
+                                `Libraries must receive values from importers via the parent manifest's variables / secrets block.`,
+                            data: { resource, filePath, path: `${block}.${entryName}.env` },
+                        });
+                    }
+                }
+            }
+        }
         // Build typed kernel globals schema so x-telo-context chain validation
         // recognises variables, secrets, resources, env automatically
         const kernelGlobals = buildKernelGlobalsSchema(allManifests);
@@ -568,6 +693,33 @@ export class StaticAnalyzer {
                     });
                 }
             }
+            // Validate inline resources nested inside this resource's body (e.g. a
+            // Run.Sequence step's `invoke: { kind, ...config }`). These sit at
+            // x-telo-ref slots reached only through local `$ref`s, which the
+            // reference field map intentionally does not follow, so they escape both
+            // inline-extraction and the per-resource schema check above.
+            if (definition.schema) {
+                // Resolve inline kinds in the parent resource's scope: direct kind
+                // first, then the parent module's own aliases (for resources declared
+                // inside an imported module), then the root aliases. Mirrors how the
+                // analyzer resolves kinds elsewhere so module-scoped aliases don't
+                // produce false UNDEFINED_KIND diagnostics.
+                const ownModule = m.metadata?.module;
+                const scopeResolver = ownModule && !rootModules.has(ownModule) ? aliasesByModule.get(ownModule) : undefined;
+                diagnostics.push(...validateNestedInlineResources(m, definition.schema, (kind) => {
+                    const direct = defs.resolve(kind);
+                    if (direct)
+                        return direct;
+                    const viaScope = scopeResolver?.resolveKind(kind);
+                    if (viaScope) {
+                        const scoped = defs.resolve(viaScope);
+                        if (scoped)
+                            return scoped;
+                    }
+                    const viaRoot = aliases.resolveKind(kind);
+                    return viaRoot ? defs.resolve(viaRoot) : undefined;
+                }));
+            }
             // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
         }
         // Template-body structural validations: check that template entry-points produce
@@ -622,15 +774,14 @@ export class StaticAnalyzer {
                     emitTargetMismatch(dispatchKind, targetSchema, md.inputs, "inputs");
                 }
             }
-            // Top-level `result:` (a sibling, only meaningful with `provide:`) is a
-            // post-call mapping that must satisfy the abstract this definition
-            // `extends` (`outputType`). The target's outputType lives on `provide.kind`
+            // Top-level `result:` is a post-call mapping that must satisfy the abstract
+            // this definition `extends` (`outputType`). It's a sibling of whichever
+            // dispatch entry-point declared a kind-typed target (`provide:` or
+            // `invoke:`). The target's outputType lives on the dispatcher's `kind`
             // and is what `result` is typed against *inside* CEL — separate role.
-            if (provide &&
-                typeof provide === "object" &&
-                !Array.isArray(provide) &&
-                md.result &&
-                typeof md.result === "object") {
+            const hasDispatchObject = (provide && typeof provide === "object" && !Array.isArray(provide)) ||
+                (invoke && typeof invoke === "object" && !Array.isArray(invoke));
+            if (hasDispatchObject && md.result && typeof md.result === "object") {
                 const extendsValue = md.extends;
                 if (typeof extendsValue === "string" && extendsValue.length > 0) {
                     const abstractSchema = lookupDefinitionTypeField(extendsValue, "outputType", defs, aliases, allManifests);
@@ -694,8 +845,18 @@ export class StaticAnalyzer {
                     effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
                 }
                 const engine = defaultRegistry().get(engineName);
-                if (!engine)
+                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") {
@@ -735,16 +896,25 @@ export class StaticAnalyzer {
         diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }));
         // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
         diagnostics.push(...validateExtends(allManifests, defs, aliases));
+        // Validate provider coherence rules for `provide:` template-target definitions.
+        diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
         // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
         diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
-        return diagnostics;
+        // 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);
     }
     analyzeErrors(manifests, options, registry) {
         return this.analyze(manifests, options, registry).filter((d) => d.severity === DiagnosticSeverity.Error);
     }
     normalize(manifests, registry) {
         const ctx = registry._context();
-        return normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        const normalized = normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        // Resolve !ref sentinels after normalize so both the original and
+        // inline-extracted manifests get their refs canonicalized to
+        // {kind, name} for the kernel that consumes this output.
+        resolveRefSentinels(normalized, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        return normalized;
     }
     prepare(manifests, registry) {
         const ctx = registry._context();

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,EAwQ/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,EAiU/C,CAAC"}

package/dist/builtins.js

@@ -147,7 +147,12 @@ export const KERNEL_BUILTINS = [
                         additionalProperties: false,
                         properties: {
                             self: { "x-telo-context-from-root": "schema" },
-                            result: { "x-telo-context-from-ref-kind": "provide/kind#outputType" },
+                            result: {
+                                "x-telo-context-from-ref-kind": [
+                                    "provide/kind#outputType",
+                                    "invoke/kind#outputType",
+                                ],
+                            },
                         },
                     },
                 },
@@ -213,6 +218,20 @@ export const KERNEL_BUILTINS = [
                         anyOf: [
                             { type: "string", "x-telo-ref": "telo#Runnable" },
                             { type: "string", "x-telo-ref": "telo#Service" },
+                            // Post-resolution shape that `resolveRefSentinels`
+                            // substitutes a `!ref <name>` sentinel into. The
+                            // adjacent `x-telo-ref` constraints govern the kind
+                            // check; this branch only admits the structural form so
+                            // AJV doesn't reject a resolved ref.
+                            {
+                                type: "object",
+                                required: ["kind", "name"],
+                                properties: {
+                                    kind: { type: "string" },
+                                    name: { type: "string" },
+                                },
+                                additionalProperties: true,
+                            },
                         ],
                     },
                 },
@@ -220,6 +239,44 @@ export const KERNEL_BUILTINS = [
                     type: "array",
                     items: { type: "string" },
                 },
+                // Application-level environment contract. Each entry layers `env:`
+                // (required, names the source env var) and `default:` (optional, used
+                // when the env var is unset) on top of an open JSON Schema property
+                // schema. `type:` constrains the coercion rule applied to the raw env
+                // string (scalars per-type; `object` / `array` via JSON.parse with the
+                // matching top-level type). All other JSON Schema keywords are passed
+                // through unchanged and applied to the coerced value via the standard
+                // schema validator. See kernel/nodejs/src/application-env.ts.
+                variables: {
+                    type: "object",
+                    additionalProperties: {
+                        type: "object",
+                        required: ["env", "type"],
+                        properties: {
+                            env: { type: "string" },
+                            type: {
+                                type: "string",
+                                enum: ["string", "integer", "number", "boolean", "object", "array"],
+                            },
+                            default: {},
+                        },
+                    },
+                },
+                secrets: {
+                    type: "object",
+                    additionalProperties: {
+                        type: "object",
+                        required: ["env", "type"],
+                        properties: {
+                            env: { type: "string" },
+                            type: {
+                                type: "string",
+                                enum: ["string", "integer", "number", "boolean", "object", "array"],
+                            },
+                            default: {},
+                        },
+                    },
+                },
             },
             required: ["metadata"],
             additionalProperties: false,

package/dist/definition-registry.d.ts

@@ -31,8 +31,19 @@ export declare class DefinitionRegistry {
      *  Returns undefined when the module identity is not yet registered. */
     computeId(moduleName: string, typeName: string): string | undefined;
     /** Validates data against a schema using this registry's AJV instance, which has all
-     *  registered definition schemas loaded — enabling cross-module $ref resolution. */
+     *  registered definition schemas loaded — enabling cross-module $ref resolution.
+     *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
+     *  owning definition) by `schemaCompileError` via the analyzer's
+     *  definition-schema compile check, so resources are never silently skipped. */
     validateWithRefs(data: unknown, schema: Record<string, any>): string[];
+    /** Returns the AJV compile error for `schema`, or `undefined` when it compiles.
+     *  Compiles on this registry's instance, which has every loaded module schema
+     *  plus the manifest root registered, so local `#/$defs`, `telo://manifest`,
+     *  and cross-module `$ref`s all resolve. Used to fail loud on a definition
+     *  schema that AJV cannot compile — otherwise `validateAgainstSchema` /
+     *  `validateWithRefs` would swallow the failure and silently skip every
+     *  resource of that kind. */
+    schemaCompileError(schema: Record<string, any>): string | undefined;
     private tryRegisterSchema;
     /** Resolves an x-telo-ref string to a canonical registry kind key.
      *  Splits on "#", looks up the left side in the identity table, and returns

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,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAGlC,+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;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAuBhC,OAAO,CAAC,uBAAuB;IA+B/B;;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,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAGlC,+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;IA+B1E;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;;;;oFAIgF;IAChF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE;;;;;;iCAM6B;IAC7B,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS;IASnE,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;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAuBhC,OAAO,CAAC,uBAAuB;IA+B/B;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}

package/dist/definition-registry.js

@@ -70,6 +70,22 @@ export class DefinitionRegistry {
      *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
      *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
     registerModuleIdentity(namespace, moduleName) {
+        // The "telo" identity is reserved for the Telo built-in module and gets
+        // populated automatically when a Telo.Abstract definition registers (see
+        // `register` below). A user app / library without a namespace must NOT
+        // claim it — silently overwriting the built-in entry breaks every
+        // x-telo-ref that resolves through "telo#…". Concretely, the
+        // `Http.Api.routes[].handler` slot in the http-server schema carries
+        // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
+        // `Telo.Application/HelloApi` (no namespace), this method previously
+        // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
+        // ref then resolved to a nonexistent `HelloApi.Invocable`, the
+        // kind-mismatch check inside `validate-references.ts` short-circuited
+        // on partial context, and the analyzer reported zero issues for a
+        // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
+        // they have no x-telo-ref identity to declare anyway.
+        if (!namespace && moduleName !== "Telo")
+            return;
         const identity = namespace ? `${namespace}/${moduleName}` : "telo";
         this.identityMap.set(identity, moduleName);
         this.reverseIdentityMap.set(moduleName, identity);
@@ -89,7 +105,10 @@ export class DefinitionRegistry {
         return `${identity}/${typeName}`;
     }
     /** Validates data against a schema using this registry's AJV instance, which has all
-     *  registered definition schemas loaded — enabling cross-module $ref resolution. */
+     *  registered definition schemas loaded — enabling cross-module $ref resolution.
+     *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
+     *  owning definition) by `schemaCompileError` via the analyzer's
+     *  definition-schema compile check, so resources are never silently skipped. */
     validateWithRefs(data, schema) {
         let validate;
         try {
@@ -102,6 +121,22 @@ export class DefinitionRegistry {
             return [];
         return (validate.errors ?? []).map(formatSingleError);
     }
+    /** Returns the AJV compile error for `schema`, or `undefined` when it compiles.
+     *  Compiles on this registry's instance, which has every loaded module schema
+     *  plus the manifest root registered, so local `#/$defs`, `telo://manifest`,
+     *  and cross-module `$ref`s all resolve. Used to fail loud on a definition
+     *  schema that AJV cannot compile — otherwise `validateAgainstSchema` /
+     *  `validateWithRefs` would swallow the failure and silently skip every
+     *  resource of that kind. */
+    schemaCompileError(schema) {
+        try {
+            this.ajv.compile(schema);
+            return undefined;
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+    }
     tryRegisterSchema(moduleName, typeName, schema) {
         const id = this.computeId(moduleName, typeName);
         if (!id || this.registeredSchemaIds.has(id))

package/dist/dependency-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.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;AAGnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CA6FjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAkHjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}