@telorun/analyzer 0.72.0 → 0.73.0

package/dist/validate-template-body.js

@@ -0,0 +1,246 @@
+import { nearestName } from "./nearest-name.js";
+import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import { refSentinelTarget } from "./ref-sentinel-target.js";
+import { isRefEntry, resolveFieldEntries, satisfiesValueBranch } from "./reference-field-map.js";
+import { templateBodies } from "./template-body.js";
+import { DiagnosticSeverity, DiagnosticTag } from "./types.js";
+const SOURCE = "telo-analyzer";
+/** The four slots a `Telo.Definition` names its dispatch target in.
+ *
+ *  WHAT THE TARGET'S CAPABILITY IS IS DELIBERATELY NOT CHECKED. The kernel tests
+ *  METHOD PRESENCE at dispatch (`entry.instance?.invoke`), so a declared
+ *  capability says nothing about whether a dispatch works — the same structural
+ *  -versus-nominal split that keeps `use` uncross-constrained against a slot's
+ *  target. A check here read `Run.Sequence`'s `capability: Telo.Runnable` and
+ *  rejected `Ai.Buffered`, a shipping module whose sequence implements `invoke()`
+ *  over an inputs/outputs contract and dispatches correctly. Trimming the refused
+ *  set would only move that: any controller may expose a method its capability
+ *  does not name, and a template body is exactly where that is done on purpose. */
+const DISPATCH_SLOTS = ["invoke", "run", "provide", "mount"];
+/**
+ * A TEMPLATE BODY IS WRITTEN LIKE EVERY OTHER MANIFEST, AND CHECKED LIKE ONE.
+ *
+ * A `Telo.Definition` is in both reference skip sets — its body holds
+ * declarations of OTHER kinds, and its dispatch slots carry no `x-telo-ref` — so
+ * no reference pass reached it, and each rule about it was added per construct:
+ * `provide:` and `mount:` had a target check for the `{ kind, name }` object
+ * form, `!ref` had one that switched itself off for any definition with a
+ * CEL-named entry, and `invoke:` / `run:` had none. What was tagged was caught
+ * and what was a plain name was resolved by the kernel alone. This pass is the
+ * one reader of a body's reference surface, and it rests on one spelling:
+ *
+ *  - every `resources:` entry is named by a LITERAL (`TEMPLATE_ENTRY_NAME_DYNAMIC`).
+ *    Each instance of a template owns its children in a child context of its
+ *    own, so a per-instance suffix (`self.name + '-query'`) buys nothing — and a
+ *    `!ref` is looked up verbatim, so a CEL-named sibling is one nothing can name;
+ *  - a dispatch slot is `!ref <entry>` naming an entry
+ *    (`TEMPLATE_DISPATCH_UNKNOWN`); the legacy spellings are deprecated rather
+ *    than refused, since published artifacts carry them. What the target's
+ *    CAPABILITY is stays unchecked — see `DISPATCH_SLOTS`;
+ *  - a reference slot INSIDE an entry follows the rule every other slot does —
+ *    `!ref` or an inline declaration, never `{ kind, name }` or a bare string
+ *    (`INVALID_REFERENCE_FORM`) — and a bare `!ref` names a sibling or a
+ *    resource of the defining module (`TEMPLATE_REF_UNKNOWN`). Slots are found
+ *    through the nested kind's own field map, resolved in the DEFINING module's
+ *    alias scope, since that is where the body's kinds are written.
+ *
+ * Entry-module-scoped, like every other declaration check: a published
+ * dependency's template body is not the consumer's to fix. Browser-safe.
+ */
+export function validateTemplateBody(manifests, registry, aliases, aliasesByModule, rootModules) {
+    const out = [];
+    const scopes = { aliasesByModule, rootModules };
+    // A definition forwarded from an imported library is that library's to fix;
+    // the imports name them (the `validate-extends` rule).
+    const importedModules = new Set();
+    // Every named instance, by declaring module — what a body's bare `!ref` may
+    // reach beside its siblings. A manifest with no stamp belongs to the entry.
+    const instancesByModule = new Map();
+    for (const m of manifests) {
+        const name = m.metadata?.name;
+        if (typeof name !== "string")
+            continue;
+        if (m.kind === "Telo.Import") {
+            const resolved = m.metadata.resolvedModuleName;
+            if (resolved)
+                importedModules.add(resolved);
+            continue;
+        }
+        if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract")
+            continue;
+        if (m.kind === "Telo.Library" || m.kind === "Telo.Application")
+            continue;
+        const mod = m.metadata?.module;
+        let set = instancesByModule.get(mod);
+        if (!set)
+            instancesByModule.set(mod, (set = new Set()));
+        set.add(name);
+    }
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const meta = m.metadata;
+        const name = meta?.name;
+        if (!name)
+            continue;
+        if (meta?.module && importedModules.has(meta.module))
+            continue;
+        const bodies = m.resources;
+        const resourceRef = { kind: m.kind, name };
+        const filePath = meta?.source;
+        const label = `${m.kind}/${name}`;
+        const report = (code, path, message, fix) => out.push({
+            severity: DiagnosticSeverity.Error,
+            code,
+            source: SOURCE,
+            message: `${label}: ${message}`,
+            data: {
+                resource: resourceRef,
+                filePath,
+                path,
+                ...(fix ? { fix: { replacement: fix } } : {}),
+            },
+        });
+        /** A spelling the kernel still READS. Warning-grade because refusing it
+         *  would break every app pinning a version that carries it, and tagged so an
+         *  editor strikes it through rather than merely colouring it — the
+         *  `DEPRECATED_KIND` shape, for the same reason. */
+        const deprecate = (code, path, message) => out.push({
+            severity: DiagnosticSeverity.Warning,
+            code,
+            source: SOURCE,
+            message: `${label}: ${message}`,
+            tags: [DiagnosticTag.Deprecated],
+            data: { resource: resourceRef, filePath, path },
+        });
+        const entries = Array.isArray(bodies) ? bodies : [];
+        const siblings = [];
+        let anyDynamic = false;
+        entries.forEach((entry, i) => {
+            const entryName = entry?.metadata?.name;
+            if (typeof entryName === "string" && !entryName.includes("${{")) {
+                siblings.push(entryName);
+                return;
+            }
+            if (entryName === undefined)
+                return;
+            anyDynamic = true;
+            deprecate("DEPRECATED_TEMPLATE_ENTRY_NAME", `resources[${i}].metadata.name`, `a 'resources:' entry named by ${describeDynamic(entryName)} is deprecated — name it ` +
+                `with a literal and dispatch to it with '!ref'. Each instance of a template owns its ` +
+                `children in a child context of its own, so a per-instance suffix buys nothing, and a ` +
+                `'!ref' is looked up verbatim, so nothing can name a computed entry. While one is ` +
+                `present the target checks below are switched off for this kind.`);
+        });
+        // Siblings PLUS the declaring module's own resources, because that is what
+        // the runtime resolves at a reference slot: a body's `!ref` is stamped
+        // `{kind, name}` with an empty kind for a non-sibling, and Phase-5 injection
+        // dispatches by NAME and recovers the kind from the instance it finds — so
+        // `client: !ref moduleClient` in a body reaches the module-level client and
+        // works. (A step's `invoke:` is a different path that does NOT: see the
+        // `resources` note in `validate-template-body`'s own tests.)
+        const reachable = new Set([
+            ...siblings,
+            ...(instancesByModule.get(meta?.module) ?? []),
+        ]);
+        // --- dispatch slots ---
+        for (const slot of DISPATCH_SLOTS) {
+            const value = m[slot];
+            if (value == null)
+                continue;
+            if (!isRefSentinel(value)) {
+                deprecate("DEPRECATED_TEMPLATE_DISPATCH_FORM", slot, `'${slot}:' written as ${describeDispatchValue(value)} is deprecated — ` +
+                    `write '!ref <entry>', the spelling every other reference uses. ` +
+                    `Available: ${siblings.join(", ") || "(none)"}.`);
+                continue;
+            }
+            const source = value.source;
+            const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
+            if (siblings.includes(target))
+                continue;
+            // A dynamic sibling has already been reported, and might be the one
+            // meant — a second diagnostic about the same line would be noise.
+            if (anyDynamic)
+                continue;
+            const suggestion = nearestName(target, siblings);
+            report("TEMPLATE_DISPATCH_UNKNOWN", slot, `'${slot}: !ref ${source}' names no entry in 'resources:'. ` +
+                `Available: ${siblings.join(", ") || "(none)"}.` +
+                (suggestion ? ` Did you mean '${suggestion}'?` : ""), suggestion);
+        }
+        // --- reference slots inside each entry ---
+        for (const body of templateBodies(m, registry, aliases, scopes)) {
+            const kind = body.manifest.kind;
+            const fieldMap = registry.expandedFieldMapForResource({ ...body.manifest, metadata: { ...(body.manifest.metadata ?? {}), module: meta?.module } }, aliases, aliasesByModule);
+            if (!fieldMap)
+                continue;
+            for (const [fieldPath, entry] of fieldMap) {
+                if (!isRefEntry(entry))
+                    continue;
+                for (const site of resolveFieldEntries(body.manifest, fieldPath)) {
+                    const value = site.value;
+                    if (value == null)
+                        continue;
+                    const path = `${body.prefix}.${site.path}`;
+                    if (isTaggedSentinel(value)) {
+                        const target = refSentinelTarget(value);
+                        if (!target)
+                            continue;
+                        const { alias, name: refName } = target;
+                        if (alias && alias !== "Self")
+                            continue;
+                        if (reachable.has(refName))
+                            continue;
+                        const suggestion = nearestName(refName, [...reachable]);
+                        report("TEMPLATE_REF_UNKNOWN", path, `'${site.path}: !ref ${value.source}' on the ${kind} entry names no sibling ` +
+                            `'resources:' entry and no resource of this module. ` +
+                            `Siblings: ${siblings.filter((s) => s !== body.manifest.metadata?.name).join(", ") || "(none)"}.` +
+                            (suggestion ? ` Did you mean '${suggestion}'?` : ""), suggestion);
+                        continue;
+                    }
+                    const hasValueBranch = (entry.valueBranches?.length ?? 0) > 0;
+                    if (hasValueBranch && typeof value !== "object")
+                        continue;
+                    if (satisfiesValueBranch(value, entry.valueBranches, registry))
+                        continue;
+                    if (typeof value === "string") {
+                        if (value.includes("${{"))
+                            continue;
+                        report("INVALID_REFERENCE_FORM", path, `string reference at '${site.path}' on the ${kind} entry → '${value}' is not ` +
+                            `supported; write it as '!ref ${value}'`);
+                        continue;
+                    }
+                    if (value && typeof value === "object" && !Array.isArray(value)) {
+                        const obj = value;
+                        if (typeof obj.kind === "string" && obj.name !== undefined) {
+                            report("INVALID_REFERENCE_FORM", path, `object reference '{ kind, name }' at '${site.path}' on the ${kind} entry is ` +
+                                `not supported; write it as '!ref ${describeRefName(obj.name)}'`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+function describeDynamic(name) {
+    if (isTaggedSentinel(name))
+        return `the expression '${name.source}'`;
+    if (typeof name === "string")
+        return `the template '${name}'`;
+    return `a ${typeof name}`;
+}
+function describeDispatchValue(value) {
+    if (isTaggedSentinel(value))
+        return `a '!${value.engine}' expression`;
+    if (typeof value === "string")
+        return `the string '${value}'`;
+    if (value && typeof value === "object" && "name" in value)
+        return "the '{ kind, name }' object form";
+    return `a ${typeof value}`;
+}
+function describeRefName(name) {
+    if (typeof name === "string")
+        return name;
+    if (isTaggedSentinel(name))
+        return "<entry>";
+    return String(name);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,12 +43,13 @@
     "jsonpath-plus": "^10.3.0",
     "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.19.0"
+    "@telorun/templating": "0.20.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
+    "@telorun/glob": "0.3.0",
     "@telorun/sdk": "0.87.0"
   },
   "peerDependencies": {

package/src/analyzer.ts

@@ -25,7 +25,13 @@ import {
 } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { readDeprecation } from "./deprecation.js";
-import { type ContractDirection, effectiveAuthorSchema } from "./extends-resolution.js";
+import {
+  type ContractDirection,
+  type DefResolver,
+  effectiveAuthorSchema,
+  inheritedCapability,
+  inheritedRequiredFields,
+} from "./extends-resolution.js";
 import {
   analyzerContractScope,
   type ContractScope,
@@ -142,6 +148,7 @@ import {
 import {
   celEvalModeAt,
   celEvalSites,
+  implicitEvalSites,
   mergeCelEvalSites,
   NO_CEL_EVAL_SITES,
   type CelEvalSites,
@@ -172,7 +179,8 @@ import { kindSatisfies, validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
 import { isInjectedDeclaration } from "./resource-input.js";
 import { validateResourceInputs } from "./validate-resource-inputs.js";
-import { validateTemplateDispatch } from "./validate-template-dispatch.js";
+import { validateExports } from "./validate-exports.js";
+import { validateTemplateBody } from "./validate-template-body.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 import { readStepSlot } from "./step-slot.js";
@@ -2029,12 +2037,41 @@ export class StaticAnalyzer {
           allManifests as Record<string, any>[],
         );
         const issues = [...ajvIssues, ...valueSchemaIssues];
+        // WHY A FIELD THIS KIND EXISTS TO SUPPLY IS STILL REQUIRED OF ITS
+        // CONSUMER. A child that `extends` and declares no `base:` is authored
+        // against merge(parent, own), so the parent's `required` stays on the
+        // CHILD's surface — and a kind written to wire that field internally
+        // then demands it from the consumer anyway. The `base:` mapping is what
+        // narrows (with it the surface is the child's own schema alone), and
+        // nothing in "is missing required property" points there, which is what
+        // turns one mistake into a three-step dead end.
+        //
+        // Matched against names DERIVED from the parent, never by parsing the
+        // message: which fields are inherited is a fact about the definition,
+        // and a check that reads a validator's prose breaks when the prose does.
+        const inheritedRequired = inheritedRequiredFields(definition, (k) =>
+          defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+        );
+        const parentKind = (definition as { extends?: string } | undefined)?.extends;
         for (const issue of issues) {
+          // Keyed on the STRUCTURED failure, never on the sentence: the field
+          // names are derived from the parent, and matching them against the
+          // validator's prose would break when the prose changes and mis-fire on
+          // any other issue quoting the same name (an `additionalProperties`
+          // rejection, an `enum` listing).
+          const inherited =
+            issue.keyword === "required" && issue.missingProperty !== undefined
+              ? inheritedRequired.filter((f) => f === issue.missingProperty)
+              : [];
+          const hint =
+            inherited.length > 0 && parentKind
+              ? ` — ${inherited.map((f) => `'${f}'`).join(", ")} ${inherited.length > 1 ? "come" : "comes"} from '${parentKind}', which this kind extends without a 'base:' mapping, so the parent's required fields stay on this kind's author surface. Add 'base:' to set them internally; that also narrows the surface to this kind's own schema.`
+              : "";
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
             code: "SCHEMA_VIOLATION",
             source: SOURCE,
-            message: `${m.kind}/${resource.name}: ${issue.message}`,
+            message: `${m.kind}/${resource.name}: ${issue.message}${hint}`,
             data: { resource, filePath, path: issue.path },
           });
         }
@@ -2472,8 +2509,15 @@ export class StaticAnalyzer {
 
           // The non-eval-field check only applies to runtime resource instances:
           // structural / templating kinds (capability `Telo.Template`, or no
-          // definition) carry CEL the kernel evaluates by other rules.
-          const capability = e.definition?.capability;
+          // definition) carry CEL the kernel evaluates by other rules. The
+          // capability is INHERITED along `extends` — an inheritance kind
+          // writes none of its own — and reading the declared one left the
+          // rule off for every such kind, and its expressions untyped.
+          const resolveDef: DefResolver = (k) =>
+            defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k);
+          const capability = e.definition
+            ? inheritedCapability(e.definition as unknown as ResourceDefinition, resolveDef)
+            : undefined;
           celRuleApplies =
             !!e.definition?.schema && capability !== undefined && capability !== "Telo.Template";
           if (celRuleApplies) {
@@ -2487,15 +2531,18 @@ export class StaticAnalyzer {
             // disagreeing about what the manifest means.
             const ownSchema = effectiveAuthorSchema(
               e.definition as unknown as ResourceDefinition,
-              (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+              resolveDef,
             ) as Record<string, any>;
             const capabilityDef = capability ? defs.resolve(capability) : undefined;
             // A `Telo.Provider`'s fields are implicitly compile-eval — the
             // capability abstract carries the root annotation — so its reads are
-            // covered here without the provider restating anything.
+            // covered here without the provider restating anything. A base-form
+            // child's own fields are too (`implicitEvalSites`): `base:` reads
+            // them once at create().
             celSites = mergeCelEvalSites(
               celEvalSites(ownSchema),
               celEvalSites(capabilityDef?.schema as Record<string, any> | undefined),
+              implicitEvalSites(e.definition as { base?: unknown }),
             );
           } else {
             celSites = NO_CEL_EVAL_SITES;
@@ -2801,10 +2848,16 @@ export class StaticAnalyzer {
     // Warn about declared variables / secrets / ports that no CEL references.
     diagnostics.push(...validateUnusedDeclarations(allManifests, this.celEnv));
 
-    // A `!ref` at a definition's dispatch slot must name a sibling `resources:`
-    // entry — the slot no reference pass reaches, so the tag would otherwise
-    // advertise a resolution nothing performs.
-    diagnostics.push(...validateTemplateDispatch(allManifests, rootModules));
+    // A template body's reference surface — its entry names, its dispatch slots
+    // and the ref slots inside each entry — which no reference pass reaches,
+    // since a `Telo.Definition` is in both skip sets.
+    diagnostics.push(
+      ...validateTemplateBody(allManifests, defs, aliases, aliasesByModule, rootModules),
+    );
+
+    // A library's export list, resolved against what it declares — otherwise a
+    // listed name that exists nowhere fails in the consumer's file.
+    diagnostics.push(...validateExports(allManifests, defs, aliases, rootModules));
 
     // A library's declared resource inputs, and every import that supplies them.
     diagnostics.push(

package/src/builtins.ts

@@ -23,6 +23,62 @@ const observedStateSlot = {
     "What a resource of this kind reports while running, published at `resources.<name>.status.<field>`.",
   $ref: manifestFragmentRef("JsonSchema7"),
 };
+
+/** The `self`-only CEL scope a dispatch slot's name template is written in. */
+const dispatchSelfContext = {
+  type: "object",
+  additionalProperties: false,
+  properties: { self: { "x-telo-context-from-root": "schema" } },
+};
+
+/**
+ * A `Telo.Definition` dispatch slot: which `resources:` entry receives the call.
+ *
+ * Three shapes, and the union is what keeps the slot CONSTRAINED for manifests
+ * no pass walks — `validate-template-body` resolves the target and its
+ * capability, but it is entry-scoped, so a dependency's definition would
+ * otherwise have nothing checking this slot at all. An array or a number fails
+ * every branch here, which is the floor AJV used to provide.
+ *
+ * `anyOf`, never `oneOf`: a `!ref` sentinel is an object, so it would match both
+ * the sentinel branch and any permissive object branch and then fail for
+ * matching twice. That is also how the sentinel used to pass — the legacy object
+ * branch required nothing, so it accepted one by accident; here it is a branch
+ * of its own that says so.
+ */
+function dispatchSlot(title: string, description: string): Record<string, unknown> {
+  return {
+    title,
+    description,
+    anyOf: [
+      // `!ref <entry>` — the spelling to write.
+      {
+        type: "object",
+        required: ["__tagged", "engine", "source"],
+        properties: {
+          __tagged: { const: true },
+          engine: { const: "ref" },
+          source: { type: "string", minLength: 1 },
+        },
+        additionalProperties: false,
+      },
+      // Legacy: a name template expanded against `self`. Read forever, because
+      // published artifacts carry it; `DEPRECATED_TEMPLATE_DISPATCH_FORM` is
+      // what moves an author off it.
+      { type: "string", "x-telo-context": dispatchSelfContext },
+      // Legacy: `{ kind?, name }`, where `name` is that same template.
+      {
+        type: "object",
+        required: ["name"],
+        properties: {
+          kind: { type: "string" },
+          name: { type: "string", "x-telo-context": dispatchSelfContext },
+        },
+        additionalProperties: true,
+      },
+    ],
+  };
+}
 import type { ResourceDefinition } from "@telorun/sdk";
 
 /** Descriptive provenance a module declares about itself, shared by
@@ -480,99 +536,31 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
-        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" },
-            },
-          },
-        },
-        // Mount dispatch: names the `resources:` entry (a Telo.Mount, e.g. an
-        // Http.Api) whose `register()` this definition delegates to. Same
-        // string / { kind, name } grammar as `invoke:`. The named child stays
-        // persistent so the produced mount's routes can `!ref` its siblings.
-        mount: {
-          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" },
-                    },
-                  },
-                },
-              },
-            },
-          ],
-        },
+        // A dispatch slot names the `resources:` entry that receives the call,
+        // as `!ref <entry>` — the one spelling every reference in Telo has. The
+        // string and `{ kind, name }` forms it used to admit (a CEL name
+        // template matched against CEL-named entries) were the removed
+        // reference object surviving in the one place nothing resolved it;
+        // `validate-template-body` is what resolves this slot, so the schema
+        // stays open here rather than reporting the same defect twice.
+        invoke: dispatchSlot(
+          "Invoke target",
+          "The `resources:` entry whose `invoke()` this kind dispatches to, as `!ref <entry>`.",
+        ),
+        provide: dispatchSlot(
+          "Provide target",
+          "The `resources:` entry whose `invoke()` produces this provider's value, as `!ref <entry>`.",
+        ),
+        run: dispatchSlot(
+          "Run target",
+          "The `resources:` entry whose `run()` this kind dispatches to, as `!ref <entry>`.",
+        ),
+        // The named child stays persistent so the produced mount's routes can
+        // `!ref` its siblings.
+        mount: dispatchSlot(
+          "Mount target",
+          "The `resources:` entry (a Telo.Mount, e.g. an Http.Api) whose `register()` this kind delegates to, as `!ref <entry>`.",
+        ),
         inputs: {
           type: "object",
           additionalProperties: true,
@@ -593,11 +581,11 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             additionalProperties: false,
             properties: {
               self: { "x-telo-context-from-root": "schema" },
+              // Typed from the dispatch target's declared output: the slot
+              // holds a `!ref` to a `resources:` entry, resolved to that
+              // entry's kind (or its own `outputType`, where it narrows one).
               result: {
-                "x-telo-context-from-ref-kind": [
-                  "provide/kind#outputType",
-                  "invoke/kind#outputType",
-                ],
+                "x-telo-context-from-ref-kind": ["provide#outputType", "invoke#outputType"],
               },
             },
           },