@telorun/analyzer 0.32.0 → 0.34.0

package/src/analysis-registry.ts

@@ -262,16 +262,17 @@ export class AnalysisRegistry {
     const targetDef = this.defs.resolve(targetKind);
     if (!targetDef) return undefined;
 
+    // General single inheritance: the accepted set is the target kind plus every
+    // kind that transitively extends it (subtypes are substitutable). A concrete
+    // target contributes itself and any specializations; an abstract contributes
+    // its implementations. Same transitive index for both.
     const out = new Set<string>();
-    if (targetDef.kind === "Telo.Abstract") {
-      for (const def of this.defs.getByExtends(targetKind)) {
-        const module = (def.metadata as { module?: string } | undefined)?.module;
-        if (module && def.metadata?.name) {
-          out.add(`${module}.${def.metadata.name as string}`);
-        }
+    if (targetDef.kind !== "Telo.Abstract") out.add(targetKind);
+    for (const def of this.defs.getByExtends(targetKind)) {
+      const module = (def.metadata as { module?: string } | undefined)?.module;
+      if (module && def.metadata?.name) {
+        out.add(`${module}.${def.metadata.name as string}`);
       }
-    } else {
-      out.add(targetKind);
     }
     return out;
   }

package/src/analyzer.ts

@@ -1,7 +1,7 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-import { defaultRegistry, isTaggedSentinel } from "@telorun/templating";
+import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver, scopeResolverForModule } from "./alias-resolver.js";
 import { AnalysisRegistry } from "./analysis-registry.js";
 import {
@@ -11,6 +11,7 @@ import {
   type CelHandlers,
 } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
+import { effectiveAuthorSchema } from "./extends-resolution.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kernel-globals.js";
 import { computeSuggestKind } from "./kind-suggest.js";
@@ -39,7 +40,9 @@ import {
 } from "./validate-cel-context.js";
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
 import { validateExtends } from "./validate-extends.js";
+import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
+import { validateKindDescriptions } from "./validate-kind-descriptions.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
@@ -122,8 +125,20 @@ const SOURCE = "telo-analyzer";
  *  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: Record<string, any>): Record<string, any> {
-  const userSchema = (definition.schema ?? {}) as Record<string, any>;
+function buildSelfSchema(
+  definition: Record<string, any>,
+  defs?: DefinitionRegistry,
+  aliases?: AliasResolver,
+): Record<string, any> {
+  // The author-facing schema resolves inheritance: with `base:` the child's own
+  // schema (the parent's config is internal); without it, `merge(parent, own)`.
+  const userSchema = (
+    defs
+      ? effectiveAuthorSchema(definition as unknown as ResourceDefinition, (k) =>
+          defs.resolve(aliases?.resolveKind(k) ?? k) ?? defs.resolve(k),
+        )
+      : (definition.schema ?? {})
+  ) as Record<string, any>;
   const userProps = (userSchema.properties ?? {}) as Record<string, any>;
   const userRequired = Array.isArray(userSchema.required) ? userSchema.required : [];
   return {
@@ -192,7 +207,7 @@ function manifestRootForResolver(
   const inputs = lookupTemplateInputsSchema(m, defs, aliases, allManifests);
   return {
     ...m,
-    schema: buildSelfSchema(m),
+    schema: buildSelfSchema(m, defs, aliases),
     ...(inputs ? { inputType: inputs } : {}),
   };
 }
@@ -236,6 +251,73 @@ function gatherPropertySchemas(schema: Record<string, any>): Array<[string, Reco
   return out;
 }
 
+/**
+ * Generic, role-driven walk over an `x-telo-step-context` step array. Calls
+ * `visit(step, stepPath)` for every step — top-level and nested through the
+ * `x-telo-topology-role` forms (`branch`, `branch-list`, `case-map`). This is
+ * the single definition of how steps nest, shared by `buildStepContextSchema`
+ * (which types `steps.<name>.result`) and `validateStepInvokeReferences` (which
+ * checks invoke refs), so the topology contract lives in one place — adding a
+ * role or nesting form updates both consumers at once. No resource kind is
+ * hardcoded; recursion is driven entirely by the schema annotations.
+ */
+function walkStepArray(
+  steps: unknown[],
+  stepItemSchema: Record<string, any> | undefined,
+  rootSchema: Record<string, any>,
+  basePath: string,
+  visit: (step: Record<string, any>, stepPath: string) => void,
+): void {
+  const dispatchRole = (
+    data: unknown,
+    role: string,
+    itemsSchema: Record<string, any> | undefined,
+    path: string,
+  ): void => {
+    if (role === "branch" && Array.isArray(data)) {
+      walkStepArray(data, stepItemSchema, rootSchema, path, visit);
+    } else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+      for (const [caseKey, arr] of Object.entries(data as Record<string, unknown>)) {
+        if (Array.isArray(arr)) walkStepArray(arr, stepItemSchema, rootSchema, `${path}.${caseKey}`, visit);
+      }
+    } else if (role === "branch-list" && Array.isArray(data)) {
+      const entrySchema = resolveLocalRef(itemsSchema, rootSchema);
+      if (!entrySchema) return;
+      data.forEach((entry, i) => {
+        if (!entry || typeof entry !== "object") return;
+        for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
+          const subRole = subSchema["x-telo-topology-role"];
+          if (typeof subRole !== "string") continue;
+          dispatchRole(
+            (entry as Record<string, any>)[subKey],
+            subRole,
+            subSchema.items as Record<string, any> | undefined,
+            `${path}[${i}].${subKey}`,
+          );
+        }
+      });
+    }
+  };
+
+  steps.forEach((step, i) => {
+    if (!step || typeof step !== "object") return;
+    const s = step as Record<string, any>;
+    const stepPath = `${basePath}[${i}]`;
+    visit(s, stepPath);
+    if (!stepItemSchema) return;
+    for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
+      const role = propSchema["x-telo-topology-role"];
+      if (typeof role !== "string") continue;
+      dispatchRole(
+        s[propKey],
+        role,
+        propSchema.items as Record<string, any> | undefined,
+        `${stepPath}.${propKey}`,
+      );
+    }
+  });
+}
+
 /**
  * Build a `steps` context schema from `x-telo-step-context` annotation.
  * Walks each step in the manifest array, resolves the invoked resource's outputType,
@@ -290,90 +372,47 @@ function buildStepContextSchema(
 
     const stepProperties: Record<string, any> = {};
 
-    const dispatchRole = (
-      data: unknown,
-      role: string,
-      itemsSchema: Record<string, any> | undefined,
-    ): void => {
-      if (role === "branch" && Array.isArray(data)) {
-        collectSteps(data);
-      } else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
-        for (const arr of Object.values(data as Record<string, unknown>)) {
-          if (Array.isArray(arr)) collectSteps(arr);
-        }
-      } else if (role === "branch-list" && Array.isArray(data)) {
-        const entrySchema = resolveLocalRef(itemsSchema, defSchema);
-        if (!entrySchema) return;
-        for (const entry of data) {
-          if (!entry || typeof entry !== "object") continue;
-          for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
-            const subRole = subSchema["x-telo-topology-role"];
-            if (typeof subRole !== "string") continue;
-            dispatchRole(
-              (entry as Record<string, any>)[subKey],
-              subRole,
-              subSchema.items as Record<string, any> | undefined,
-            );
-          }
+    walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s) => {
+      const name = s.name;
+      const invoke = s[invokeField] as Record<string, any> | undefined;
+      // Only invoke steps register a `steps.<name>.result` entry — control-flow
+      // wrappers (try/if/while/switch/throw) don't produce a result and must
+      // not shadow real entries with a permissive `additionalProperties: true`,
+      // or unknown step references slip through chain validation.
+      if (typeof name !== "string" || !invoke || typeof invoke !== "object") return;
+      let outputSchema: Record<string, any> | undefined;
+      const invokedKind = invoke.kind as string | undefined;
+      const invokedName = invoke.name as string | undefined;
+      if (invokedName) {
+        const invokedManifest = allManifests.find(
+          (m) =>
+            (m.metadata as any)?.name === invokedName &&
+            (!invokedKind || m.kind === invokedKind),
+        ) as Record<string, any> | undefined;
+        if (invokedManifest) {
+          outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
         }
+      } else {
+        outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
       }
-    };
-
-    function collectSteps(items: unknown[]): void {
-      for (const step of items) {
-        if (!step || typeof step !== "object") continue;
-        const s = step as Record<string, any>;
-        const name = s.name;
-        const invoke = s[invokeField] as Record<string, any> | undefined;
-        // Only invoke steps register a `steps.<name>.result` entry — control-flow
-        // wrappers (try/if/while/switch/throw) don't produce a result and must
-        // not shadow real entries with a permissive `additionalProperties: true`,
-        // or unknown step references slip through chain validation.
-        if (typeof name === "string" && invoke && typeof invoke === "object") {
-          let outputSchema: Record<string, any> | undefined;
-          const invokedKind = invoke.kind as string | undefined;
-          const invokedName = invoke.name as string | undefined;
-          if (invokedName) {
-            const invokedManifest = allManifests.find(
-              (m) =>
-                (m.metadata as any)?.name === invokedName &&
-                (!invokedKind || m.kind === invokedKind),
-            ) as Record<string, any> | undefined;
-            if (invokedManifest) {
-              outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
-            }
-          } else {
-            outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
-          }
-          // Fallback: pull outputType from the kind's Telo.Definition. The
-          // resource manifest typically doesn't carry outputType; the def does.
-          if (!outputSchema && invokedKind) {
-            outputSchema = lookupDefinitionTypeField(
-              invokedKind,
-              outputTypeField,
-              defs,
-              aliases,
-              allManifests,
-            );
-          }
-          stepProperties[name] = {
-            type: "object",
-            properties: {
-              result: outputSchema ?? { type: "object", additionalProperties: true },
-            },
-          };
-        }
-        if (stepItemSchema) {
-          for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
-            const role = propSchema["x-telo-topology-role"];
-            if (typeof role !== "string") continue;
-            dispatchRole(s[propKey], role, propSchema.items as Record<string, any> | undefined);
-          }
-        }
+      // Fallback: pull outputType from the kind's Telo.Definition. The
+      // resource manifest typically doesn't carry outputType; the def does.
+      if (!outputSchema && invokedKind) {
+        outputSchema = lookupDefinitionTypeField(
+          invokedKind,
+          outputTypeField,
+          defs,
+          aliases,
+          allManifests,
+        );
       }
-    }
-
-    collectSteps(steps);
+      stepProperties[name] = {
+        type: "object",
+        properties: {
+          result: outputSchema ?? { type: "object", additionalProperties: true },
+        },
+      };
+    });
 
     if (Object.keys(stepProperties).length > 0) {
       return {
@@ -386,6 +425,192 @@ function buildStepContextSchema(
   return undefined;
 }
 
+/**
+ * Capabilities whose instances structurally expose no `invoke`/`run` method, so
+ * a step `invoke` of one always fails at runtime with ERR_RESOURCE_NOT_INVOKABLE
+ * (kernel dispatch checks method presence, not capability — evaluation-context.ts).
+ * `Telo.Service` is intentionally absent: some services are invocable (a function
+ * handler dispatched directly, e.g. `Lambda.Function`), so it can't be rejected
+ * statically without false positives. This is the sound subset of the runtime rule.
+ */
+const NON_INVOKABLE_CAPABILITIES = new Set([
+  "Telo.Provider",
+  "Telo.Mount",
+  "Telo.Type",
+  "Telo.Template",
+]);
+
+/**
+ * Validate `x-telo-step-context` step `invoke` references (e.g. `Run.Sequence`
+ * steps).
+ *
+ * The reference field map deliberately does NOT descend into step `invoke`
+ * slots — they sit behind a local `$ref` to the shared step definition, and
+ * turning the descent on would make Phase 5 inject live instances there,
+ * breaking the invoke dispatch path (see `reference-field-map.ts`). A
+ * consequence is that `validateReferences` never sees these slots, so a bad
+ * step invoke passes `telo check` and only fails at runtime. This pass covers
+ * exactly those slots, in two dimensions:
+ *   - Existence: an `invoke: !ref <name>` that names a missing instance — or a
+ *     *kind* instead of an exported instance (`!ref Stream.Of`) — is a still-a-
+ *     sentinel after Phase 2.5 resolution → `UNRESOLVED_REFERENCE` (runtime
+ *     `ERR_RESOURCE_NOT_FOUND`).
+ *   - Invokability: a resolved instance whose capability structurally has no
+ *     invoke/run method (`NON_INVOKABLE_CAPABILITIES`) → `REFERENCE_KIND_MISMATCH`
+ *     (runtime `ERR_RESOURCE_NOT_INVOKABLE`).
+ *
+ * Generic and topology-driven — it walks steps via the same `x-telo-step-context`
+ * / `x-telo-topology-role` annotations `buildStepContextSchema` uses (through the
+ * shared `walkStepArray`), so nested branches (then/else/do/catch/cases) are
+ * covered and no `Run.Sequence` field name is hardcoded. The cross-module
+ * partial-analysis guard mirrors `validateReferences`, so a reference into an
+ * unloaded import is skipped rather than false-flagged.
+ */
+function validateStepInvokeReferences(
+  allManifests: Record<string, any>[],
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  // Local instance names + loaded-module set — same construction as
+  // validateReferences, so the cross-module guard behaves identically.
+  const localNames = new Set<string>();
+  const loadedModules = new Set<string>();
+
+  // Also collect names of resources nested inside a manifest tree — notably
+  // `with:`-scoped resources (an `x-telo-scope` region the field map does not
+  // extract to a top-level manifest). A step can invoke one by bare name, so
+  // omitting them would false-flag a valid `!ref`. Conservative: any nested
+  // object carrying both a `kind` and a `metadata.name` is a resource
+  // definition; scope visibility is left to the runtime.
+  const collectNestedNames = (value: unknown): void => {
+    if (!value || typeof value !== "object" || isTaggedSentinel(value)) return;
+    if (Array.isArray(value)) {
+      for (const item of value) collectNestedNames(item);
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    const name = (obj.metadata as { name?: unknown } | undefined)?.name;
+    if (typeof obj.kind === "string" && typeof name === "string") localNames.add(name);
+    for (const v of Object.values(obj)) collectNestedNames(v);
+  };
+
+  for (const r of allManifests) {
+    if (r.kind === "Telo.Import") {
+      const m = (r.metadata as { resolvedModuleName?: unknown } | undefined)?.resolvedModuleName;
+      if (typeof m === "string") loadedModules.add(m);
+      continue;
+    }
+    const meta = r.metadata as { name?: unknown; module?: unknown; forwardedExport?: unknown };
+    if (typeof meta?.name !== "string" || REF_VALIDATION_SKIP_KINDS.has(r.kind)) continue;
+    if (meta.forwardedExport === true) {
+      if (typeof meta.module === "string") loadedModules.add(meta.module);
+      continue;
+    }
+    localNames.add(meta.name);
+    collectNestedNames(r);
+  }
+
+  const validateInvoke = (
+    value: unknown,
+    resource: { kind: string; name: string },
+    filePath: string | undefined,
+    path: string,
+  ): void => {
+    if (isRefSentinel(value)) {
+      // An unresolved `!ref` is a miss: a real instance would have resolved to
+      // `{kind, name}` in Phase 2.5.
+      const refName = value.source;
+      const dot = refName.indexOf(".");
+      const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+
+      if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+        const module = aliases.moduleForAlias(aliasPrefix);
+        // Partial single-file analysis (import not loaded) — skip to avoid a false miss.
+        if (module && !loadedModules.has(module)) return;
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "UNRESOLVED_REFERENCE",
+          source: SOURCE,
+          message: `${resource.kind}/${resource.name}: step invoke at '${path}' → '${refName}' is not an exported instance of module '${module ?? aliasPrefix}' (reference a declared instance, not a kind)`,
+          data: { resource, filePath, path },
+        });
+        return;
+      }
+
+      const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+      if (localNames.has(localName)) return;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "UNRESOLVED_REFERENCE",
+        source: SOURCE,
+        message: `${resource.kind}/${resource.name}: step invoke at '${path}' → resource '${localName}' not found`,
+        data: { resource, filePath, path },
+      });
+      return;
+    }
+
+    // Resolved `{kind, name}` (or an inline `{kind, …}` definition) — the
+    // instance exists. Mirror the kernel's ERR_RESOURCE_NOT_INVOKABLE, which
+    // fires when the instance has neither an `invoke` nor a `run` method
+    // (evaluation-context.ts). That is a per-instance property, not a pure
+    // capability, so only capabilities that STRUCTURALLY expose no such method
+    // are rejected statically — Service is intentionally excluded, since some
+    // services are invocable (e.g. a function handler dispatched directly).
+    if (!value || typeof value !== "object" || Array.isArray(value)) return;
+    const kind = (value as Record<string, unknown>).kind;
+    if (typeof kind !== "string") return;
+    const capability = defs.resolve(aliases.resolveKind(kind) ?? kind)?.capability;
+    if (typeof capability === "string" && NON_INVOKABLE_CAPABILITIES.has(capability)) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "REFERENCE_KIND_MISMATCH",
+        source: SOURCE,
+        message: `${resource.kind}/${resource.name}: step invoke at '${path}' → '${kind}' is a ${capability} and cannot be invoked in a step — it has no invoke or run method (runtime ERR_RESOURCE_NOT_INVOKABLE)`,
+        data: { resource, filePath, path },
+      });
+    }
+  };
+
+  for (const m of allManifests) {
+    const meta = m.metadata as { name?: unknown; source?: unknown; forwardedExport?: unknown };
+    if (
+      typeof meta?.name !== "string" ||
+      REF_VALIDATION_SKIP_KINDS.has(m.kind) ||
+      meta.forwardedExport === true
+    )
+      continue;
+    const def = defs.resolve(aliases.resolveKind(m.kind) ?? m.kind);
+    const defSchema = def?.schema as Record<string, any> | undefined;
+    if (!defSchema?.properties) continue;
+    const resource = { kind: m.kind, name: meta.name };
+    const filePath = typeof meta.source === "string" ? meta.source : undefined;
+
+    for (const [fieldName, fieldSchema] of Object.entries(
+      defSchema.properties as Record<string, any>,
+    )) {
+      const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
+      const invokeField = stepCtx?.invoke;
+      if (!invokeField) continue;
+      const steps = m[fieldName];
+      if (!Array.isArray(steps)) continue;
+      const stepItemSchema = resolveLocalRef(
+        fieldSchema.items as Record<string, any> | undefined,
+        defSchema,
+      );
+
+      walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s, stepPath) => {
+        const invoke = s[invokeField];
+        if (invoke === undefined || invoke === null) return;
+        validateInvoke(invoke, resource, filePath, `${stepPath}.${invokeField}`);
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
 /**
  * Collect every field annotated with `x-telo-error-context` anywhere in a
  * definition schema (resolving local `$ref`s into `$defs`, cycle-safe), mapping
@@ -1019,21 +1244,28 @@ export class StaticAnalyzer {
         continue;
       }
 
-      // Validate resource config against definition schema.
+      // Validate resource config against the definition's AUTHOR-FACING schema —
+      // inheritance-resolved: with `base:` the child's own schema (parent config
+      // is internal), else `merge(parent, own)` so a `base:`-less `extends` child
+      // is validated against the inherited fields it may set. For a definition
+      // that neither extends nor uses `base:` this is exactly its own schema.
       // `kind` and `metadata` are implicit on every resource — inject them so module
       // authors don't have to repeat them when using additionalProperties: false.
-      if (definition.schema) {
+      const authorSchema = effectiveAuthorSchema(definition, (k) =>
+        defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+      );
+      if (authorSchema && Object.keys(authorSchema).length > 0) {
         const schema =
-          definition.schema.additionalProperties === false
+          authorSchema.additionalProperties === false
             ? {
-                ...definition.schema,
+                ...authorSchema,
                 properties: {
                   kind: { type: "string" },
                   metadata: { type: "object" },
-                  ...definition.schema.properties,
+                  ...authorSchema.properties,
                 },
               }
-            : definition.schema;
+            : authorSchema;
         // Phase 1: CEL type checking — walk data+schema together, check env.check() return types.
         // A Telo.Import's variables/secrets are a config-only contract evaluated against the
         // IMPORTING module's scope, so type them from the owning module doc (matched by
@@ -1409,12 +1641,22 @@ export class StaticAnalyzer {
       ...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }),
     );
 
+    // Validate step `invoke` references — the slots the reference field map
+    // deliberately skips (behind the step `$ref`), so a missing instance or a
+    // kind-instead-of-instance ref there is caught statically, not at runtime.
+    diagnostics.push(...validateStepInvokeReferences(allManifests, defs, aliases));
+
     // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
     diagnostics.push(...validateExtends(allManifests, defs, aliases));
 
+    diagnostics.push(...validateBaseMapping(allManifests, defs, aliases));
+
     // Validate provider coherence rules for `provide:` template-target definitions.
     diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
 
+    // Warn about exported kinds lacking a metadata.description (semantic-search input).
+    diagnostics.push(...validateKindDescriptions(allManifests));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(
       ...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv, aliasesByModule, rootModules),

package/src/builtins.ts

@@ -209,6 +209,21 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
+        // `base:` ("super(...)") — construction mapping for an inherited
+        // (concrete-`extends`) definition. Its CEL is evaluated once against
+        // `self` (typed from this definition's `schema:`) to build the parent
+        // kind's config. Same `self`-only scope as a resource body.
+        base: {
+          type: "object",
+          additionalProperties: true,
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+            },
+          },
+        },
       },
     },
   },

package/src/definition-registry.ts

@@ -8,6 +8,7 @@ import {
   type ReferenceFieldMap,
 } from "./reference-field-map.js";
 import { createAjv, formatSingleError, navigateJsonPointer } from "./schema-compat.js";
+import { effectiveAuthorSchema } from "./extends-resolution.js";
 
 /** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
 export class DefinitionRegistry {
@@ -37,7 +38,11 @@ export class DefinitionRegistry {
     const { name, module: mod } = definition.metadata;
     const key = mod ? `${mod}.${name}` : name;
     this.defs.set(key, definition);
-    this.fieldMaps.set(key, buildReferenceFieldMap(definition.schema ?? {}));
+    // Field maps derive from the AUTHOR-FACING (inheritance-resolved) schema, which
+    // depends on the parent — possibly registered after this child. Clear the cache
+    // so any already-computed map recomputes against the now-larger def set; the
+    // maps rebuild lazily on first `getFieldMap` (after all defs are registered).
+    this.fieldMaps.clear();
     // `capability` populates extendedBy for backward-compat with the legacy pattern where
     // a concrete definition overloaded `capability: <AbstractKind>` to mean "implements
     // this abstract." The canonical pattern is `extends` (below). Both populate the index,
@@ -204,9 +209,19 @@ export class DefinitionRegistry {
     return this.defs.get(kind);
   }
 
-  /** Returns the cached reference field map for the given kind, built once during register(). */
+  /** Returns the reference field map for the given kind, computed lazily from the
+   *  kind's AUTHOR-FACING (inheritance-resolved) schema and memoized. Lazy so a
+   *  child registered before its parent still sees the parent's inherited ref
+   *  slots once both are present. */
   getFieldMap(kind: string): ReferenceFieldMap | undefined {
-    return this.fieldMaps.get(kind);
+    const cached = this.fieldMaps.get(kind);
+    if (cached) return cached;
+    const def = this.defs.get(kind);
+    if (!def) return undefined;
+    const schema = effectiveAuthorSchema(def, (k) => this.resolve(k));
+    const map = buildReferenceFieldMap(schema ?? {});
+    this.fieldMaps.set(kind, map);
+    return map;
   }
 
   /** Returns the field map for `kind`, falling back to the alias-resolved kind when not found. */