@telorun/analyzer 0.10.1 → 0.12.0

package/dist/analyzer.js

@@ -7,13 +7,49 @@ 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 { 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
@@ -37,12 +73,89 @@ function lookupDefinitionTypeField(invokedKind, fieldName, defs, aliases, allMan
     return resolveTypeFieldToSchema(value, allManifests);
 }
 const SOURCE = "telo-analyzer";
+/** Build a closed JSON Schema for the `self` CEL variable available inside a
+ *  `Telo.Definition` template body. Mirrors the runtime template controller's
+ *  `const self = { ...resource, name: resource.metadata.name };` — every
+ *  property the user declared in `schema:` plus synthetic `name` / `kind` and
+ *  the metadata sub-object (kept open since metadata legitimately carries
+ *  arbitrary user-added fields). */
+function buildSelfSchema(definition) {
+    const userSchema = (definition.schema ?? {});
+    const userProps = (userSchema.properties ?? {});
+    const userRequired = Array.isArray(userSchema.required) ? userSchema.required : [];
+    return {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            ...userProps,
+            name: { type: "string" },
+            kind: { type: "string" },
+            metadata: {
+                type: "object",
+                additionalProperties: true,
+                properties: { name: { type: "string" } },
+            },
+        },
+        required: [...userRequired, "name", "kind"],
+    };
+}
+/** Build the JSON Schema for the `inputs` CEL variable available inside an
+ *  invocable template body. Three-layer fallback mirroring the runtime's
+ *  caller-supplied inputs:
+ *    1. The definition's own `inputType:` field (preferred).
+ *    2. The `extends:`-declared abstract's `inputType:` (so a concrete
+ *       definition inheriting a contract gets typed inputs without
+ *       redeclaring them).
+ *    3. Undefined — caller signals opaque `map<string, dyn>` upstream. */
+function lookupTemplateInputsSchema(definition, defs, aliases, allManifests) {
+    const own = resolveTypeFieldToSchema(definition.inputType, allManifests);
+    if (own)
+        return own;
+    const ext = definition.extends;
+    if (typeof ext === "string" && ext.length > 0) {
+        const canonical = aliases.resolveKind(ext) ?? ext;
+        const abstractDef = defs.resolve(canonical);
+        if (abstractDef) {
+            const inherited = resolveTypeFieldToSchema(abstractDef.inputType, allManifests);
+            if (inherited)
+                return inherited;
+        }
+    }
+    return undefined;
+}
+/** Returns a "resolver-facing" view of the manifest where the fields used as
+ *  navigation roots by Telo.Definition's `x-telo-context-from-root` annotations
+ *  have been pre-augmented:
+ *    - `schema`     → augmented `self` schema (synthetic `name`/`kind`/metadata).
+ *    - `inputType`  → resolved with extends fallback when the field isn't
+ *                     declared directly on the definition.
+ *
+ *  For non-definition manifests the original object is returned. */
+function manifestRootForResolver(m, defs, aliases, allManifests) {
+    if (m.kind !== "Telo.Definition")
+        return m;
+    const inputs = lookupTemplateInputsSchema(m, defs, aliases, allManifests);
+    return {
+        ...m,
+        schema: buildSelfSchema(m),
+        ...(inputs ? { inputType: inputs } : {}),
+    };
+}
 /**
  * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
  * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
  * the same format the analyzer uses for CEL context validation.
+ *
+ * Result is sorted by scope specificity (longer scope first) so that the
+ * per-expression resolver's first-match-wins logic picks the most-specific
+ * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
+ * could shadow a narrower descendant scope whose activation differs.
  */
 function extractContextsFromSchema(schema, path = "$") {
+    const all = collectContexts(schema, path);
+    return all.sort((a, b) => b.scope.length - a.scope.length);
+}
+function collectContexts(schema, path) {
     if (!schema || typeof schema !== "object")
         return [];
     const results = [];
@@ -51,16 +164,16 @@ function extractContextsFromSchema(schema, path = "$") {
     }
     if (schema.properties) {
         for (const [key, value] of Object.entries(schema.properties)) {
-            results.push(...extractContextsFromSchema(value, `${path}.${key}`));
+            results.push(...collectContexts(value, `${path}.${key}`));
         }
     }
     if (schema.items && typeof schema.items === "object") {
-        results.push(...extractContextsFromSchema(schema.items, `${path}[*]`));
+        results.push(...collectContexts(schema.items, `${path}[*]`));
     }
     for (const key of ["oneOf", "anyOf", "allOf"]) {
         if (Array.isArray(schema[key])) {
             for (const subschema of schema[key]) {
-                results.push(...extractContextsFromSchema(subschema, path));
+                results.push(...collectContexts(subschema, path));
             }
         }
     }
@@ -296,7 +409,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
@@ -413,6 +542,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) {
@@ -420,6 +563,36 @@ export class StaticAnalyzer {
                 byName.set(m.metadata.name, m);
             }
         }
+        // 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);
@@ -436,7 +609,11 @@ export class StaticAnalyzer {
                 });
                 continue;
             }
-            if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") {
+            // Abstracts carry only inputType / outputType schema fields and no template
+            // body — nothing for the per-resource walk to validate. Definitions are now
+            // walked: their template bodies (`resources` / `invoke` / `run` / `provide`)
+            // contain CEL that must be checked against `self` / `inputs` / `result`.
+            if (m.kind === "Telo.Abstract") {
                 continue;
             }
             const resource = { kind: m.kind, name: m.metadata?.name };
@@ -489,6 +666,75 @@ export class StaticAnalyzer {
             }
             // (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
+        // values matching the contract of their dispatch target and (for `provide:`)
+        // the abstract this definition `extends`. CEL fields inside the templated
+        // values are replaced with type-appropriate placeholders before AJV runs —
+        // same pattern as the per-resource schema validation above.
+        for (const m of allManifests) {
+            if (m.kind !== "Telo.Definition")
+                continue;
+            const filePath = m.metadata?.source;
+            const name = m.metadata?.name;
+            if (!name)
+                continue;
+            const resource = { kind: m.kind, name };
+            const md = m;
+            const emitTargetMismatch = (targetKind, valueSchema, value, path) => {
+                const substituted = substituteCelFields(value, valueSchema);
+                const issues = validateAgainstSchema(substituted, valueSchema);
+                for (const issue of issues) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "TEMPLATE_TARGET_MISMATCH",
+                        source: SOURCE,
+                        message: `${m.kind}/${name}: ${path} does not satisfy ${targetKind}'s contract: ${issue.message}`,
+                        data: { resource, filePath, path: issue.path ? `${path}.${issue.path}` : path },
+                    });
+                }
+            };
+            // Resolve the dispatch target's kind, if statically known. Object-form
+            // `invoke: { kind, name }` and `provide: { kind, name }` carry it; the
+            // string-form `invoke: "name"` does not (the matching resource entry would
+            // need to be located by expanded name — out of scope here).
+            const invoke = md.invoke;
+            const provide = md.provide;
+            let dispatchKind;
+            if (invoke && typeof invoke === "object" && !Array.isArray(invoke) && typeof invoke.kind === "string") {
+                dispatchKind = invoke.kind;
+            }
+            else if (provide &&
+                typeof provide === "object" &&
+                !Array.isArray(provide) &&
+                typeof provide.kind === "string") {
+                dispatchKind = provide.kind;
+            }
+            // Top-level `inputs:` (sibling of `invoke:` / `provide:`) carries the
+            // values passed to the dispatch target's invoke(). Validate against the
+            // target's declared `inputType` when both sides have one.
+            if (dispatchKind && md.inputs && typeof md.inputs === "object") {
+                const targetSchema = lookupDefinitionTypeField(dispatchKind, "inputType", defs, aliases, allManifests);
+                if (targetSchema) {
+                    emitTargetMismatch(dispatchKind, targetSchema, md.inputs, "inputs");
+                }
+            }
+            // 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.
+            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);
+                    if (abstractSchema) {
+                        emitTargetMismatch(extendsValue, abstractSchema, md.result, "result");
+                    }
+                }
+            }
+        }
         // Validate CEL syntax and context variable access in all manifests
         for (const m of allManifests) {
             const resource = { kind: m.kind, name: m.metadata?.name };
@@ -533,7 +779,13 @@ export class StaticAnalyzer {
                     const manifestItem = matchedScope
                         ? getManifestItem(path, matchedScope, m)
                         : m;
-                    const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, allManifests);
+                    const rootForResolver = manifestRootForResolver(m, defs, aliases, allManifests);
+                    const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
+                        manifestRoot: rootForResolver,
+                        defs,
+                        aliases,
+                        allManifests: allManifests,
+                    });
                     effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
                 }
                 const engine = defaultRegistry().get(engineName);
@@ -578,16 +830,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,EAsJ/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

@@ -38,7 +38,126 @@ export const KERNEL_BUILTINS = [
         kind: "Telo.Definition",
         metadata: { name: "Definition", module: "Telo" },
         capability: "Telo.Template",
-        schema: { type: "object" },
+        // Top-level shape stays open (`additionalProperties: true`) so this change
+        // attaches x-telo-context annotations to known template-body fields without
+        // tightening the Telo.Definition shape itself. The annotations drive
+        // static CEL validation of expressions inside `resources:` / `invoke:` /
+        // `run:` / `provide:` / top-level `inputs:` / top-level `result:` against
+        // `self` (typed from `schema:`) and `inputs` (typed from `inputType:`,
+        // falling back to the extends-declared abstract).
+        //
+        // `inputs:` and `result:` live as top-level siblings of `invoke:` / `provide:`,
+        // matching how Run.Sequence steps factor dispatch from data. The dispatch
+        // entry-point (`invoke` / `provide` / `run`) determines how `inputs`/`result`
+        // are interpreted at runtime. See analyzer/nodejs/plans/template-internal-cel-validation.md.
+        schema: {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+                resources: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        additionalProperties: true,
+                        "x-telo-context": {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                self: { "x-telo-context-from-root": "schema" },
+                                inputs: { "x-telo-context-from-root": "inputType" },
+                            },
+                        },
+                    },
+                },
+                invoke: {
+                    oneOf: [
+                        {
+                            type: "string",
+                            "x-telo-context": {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    self: { "x-telo-context-from-root": "schema" },
+                                },
+                            },
+                        },
+                        {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                kind: { type: "string" },
+                                name: {
+                                    type: "string",
+                                    "x-telo-context": {
+                                        type: "object",
+                                        additionalProperties: false,
+                                        properties: {
+                                            self: { "x-telo-context-from-root": "schema" },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    ],
+                },
+                provide: {
+                    type: "object",
+                    additionalProperties: true,
+                    properties: {
+                        kind: { type: "string" },
+                        name: {
+                            type: "string",
+                            "x-telo-context": {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    self: { "x-telo-context-from-root": "schema" },
+                                },
+                            },
+                        },
+                    },
+                },
+                run: {
+                    type: "string",
+                    "x-telo-context": {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            self: { "x-telo-context-from-root": "schema" },
+                        },
+                    },
+                },
+                inputs: {
+                    type: "object",
+                    additionalProperties: true,
+                    "x-telo-context": {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            self: { "x-telo-context-from-root": "schema" },
+                            inputs: { "x-telo-context-from-root": "inputType" },
+                        },
+                    },
+                },
+                result: {
+                    type: "object",
+                    additionalProperties: true,
+                    "x-telo-context": {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            self: { "x-telo-context-from-root": "schema" },
+                            result: {
+                                "x-telo-context-from-ref-kind": [
+                                    "provide/kind#outputType",
+                                    "invoke/kind#outputType",
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        },
     },
     {
         kind: "Telo.Definition",
@@ -99,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,
+                            },
                         ],
                     },
                 },
@@ -106,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.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;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"}

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);

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"}