@telorun/analyzer 0.45.0 → 0.47.0

package/src/analyzer.ts

@@ -1,5 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { canonicalTypeSchemaId } from "@telorun/sdk";
+import { canonicalTypeSchemaId, OBSERVED_STATE_KEY } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
 import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver, scopeResolverForModule } from "./alias-resolver.js";
@@ -14,6 +14,13 @@ 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 {
+  buildObservedStateIndex,
+  buildObservedStateResourcesSchema,
+  collectRunReachableNames,
+  observedStateRead,
+  validateObservedStateDeclarations,
+} from "./validate-observed-state.js";
 import { computeSuggestKind } from "./kind-suggest.js";
 import { visitManifest } from "./manifest-visitor.js";
 import { isModuleKind } from "./module-kinds.js";
@@ -33,6 +40,7 @@ import {
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
+  extractAccessChains,
   extractCelRegionScopes,
   extractContextsFromSchema,
   getManifestItem,
@@ -717,6 +725,16 @@ function errorContextForPath(
   return best?.schema;
 }
 
+/** Member-access chains in a CEL expression, or none when it doesn't parse.
+ *  Best-effort: a syntax error is reported by the engine pass, not here. */
+function celAccessChains(env: Environment, expr: string): string[][] {
+  try {
+    return extractAccessChains(env.parse(expr).ast);
+  } catch {
+    return [];
+  }
+}
+
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 
@@ -1135,7 +1153,7 @@ export class StaticAnalyzer {
     // {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, aliases, aliasesByModule);
+    resolveRefSentinels(allManifests, aliases, aliasesByModule, [], defs);
 
     // Phase 2.6: register each named `Telo.Type` resource's schema under its
     // canonical module-scoped id (`telo://<module>/<name>`), validate
@@ -1280,9 +1298,38 @@ export class StaticAnalyzer {
       }
     }
 
+    // What each resource reports while running (`status:`), and which resources
+    // some slot can actually start. Both feed the observed-state checks below.
+    // A RESOURCE's kind is written in the module that declares it and is never
+    // canonicalized (unlike a definition's `extends`, normalized at registration
+    // above), so an exported instance's `kind: Self.X` only resolves in its own
+    // library's scope.
+    const moduleScopes = { aliasesByModule, rootModules };
+
+    const observedState = buildObservedStateIndex(allManifests, defs, aliases, moduleScopes);
+    const reportsObservedState = [...observedState.values()].some((r) => r.status);
+    const runReachable = reportsObservedState
+      ? collectRunReachableNames(allManifests, defs, aliases)
+      : new Set<string>();
+
     // Build typed kernel globals schema so x-telo-context chain validation
     // recognises variables, secrets, resources, env automatically
-    const kernelGlobals = buildKernelGlobalsSchema(allManifests);
+    const kernelGlobals = buildKernelGlobalsSchema(allManifests, observedState);
+
+    // Fallback context for CEL in a slot with no `x-telo-context` annotation:
+    // everything stays open except the typed `.status` nodes, so unknown-field
+    // checking reaches observed state everywhere without newly rejecting any
+    // read that passes today.
+    const observedStateContext: Record<string, any> | null =
+      reportsObservedState
+        ? {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+              resources: buildObservedStateResourcesSchema(observedState, true),
+            },
+          }
+        : null;
 
     // The module doc (Application/Library) carries the Application-only `ports`
     // namespace; threaded into per-resource CEL typing so `${{ ports.X }}`
@@ -1600,6 +1647,9 @@ export class StaticAnalyzer {
     // `x-telo-step-context` / `x-telo-error-context` scopes. A `!cel` outside
     // every region is read as a literal — the runtime never evaluates it.
     let celEvalPaths: string[] = [];
+    // The compile half alone: a field that resolves at startup, where observed
+    // state cannot exist yet.
+    let celCompilePaths: string[] = [];
     let celRegionScopes: string[] = [];
     let celRuleApplies = false;
 
@@ -1639,9 +1689,14 @@ export class StaticAnalyzer {
               ? buildEvalPaths(capabilityDef.schema as Record<string, any>)
               : { compile: [], runtime: [] };
             celEvalPaths = [...own.compile, ...own.runtime, ...parent.compile, ...parent.runtime];
+            // 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.
+            celCompilePaths = [...own.compile, ...parent.compile];
             celRegionScopes = extractCelRegionScopes(ownSchema);
           } else {
             celEvalPaths = [];
+            celCompilePaths = [];
             celRegionScopes = [];
           }
         },
@@ -1674,6 +1729,44 @@ export class StaticAnalyzer {
             return;
           }
 
+          // Observed state exists only while the application runs, so a path
+          // through `.status` is illegal in a field that resolves at startup —
+          // and a resource nothing can start reports nothing, ever. Both are
+          // decided from the expression and the manifest alone.
+          if (reportsObservedState && engineName === "cel" && expr.includes(OBSERVED_STATE_KEY)) {
+            for (const chain of celAccessChains(this.celEnv, expr)) {
+              const read = observedStateRead(chain);
+              if (!read) continue;
+              // An import's exported instance is indexed under `<Alias>.<name>`,
+              // the two-level shape it publishes under, so a cross-module read
+              // is checked exactly like a local one.
+              const reported = observedState.get(
+                read.alias ? `${read.alias}.${read.name}` : read.name,
+              );
+
+              if (celRuleApplies && evalPathsCover(celCompilePaths, path)) {
+                diagnostics.push({
+                  severity: DiagnosticSeverity.Error,
+                  code: "OBSERVED_STATE_IN_STARTUP_FIELD",
+                  source: SOURCE,
+                  message: `${m.kind}/${resource.name}: '${path}' is resolved once at startup, so '${chain.join(".")}' does not exist yet — '${read.name}' reports it only while the application is running. Read reported values where the call happens: a step's inputs:, a request's url, a route handler, or a returns: expression.`,
+                  data: { resource, filePath, path },
+                });
+                continue;
+              }
+
+              if (reported && !runReachable.has(read.name)) {
+                diagnostics.push({
+                  severity: DiagnosticSeverity.Error,
+                  code: "OBSERVED_STATE_NEVER_RUN",
+                  source: SOURCE,
+                  message: `${m.kind}/${resource.name}: '${read.name}' reports '${read.field ?? OBSERVED_STATE_KEY}' only while it is running, and nothing starts it. Add '!ref ${read.name}' to a targets: list, or invoke it from a step.`,
+                  data: { resource, filePath, path },
+                });
+              }
+            }
+          }
+
           let matchedContext: Record<string, any> | undefined =
             e.contextSchema ?? celInvocationContext;
 
@@ -1723,6 +1816,12 @@ export class StaticAnalyzer {
               allManifests: allManifests as Record<string, any>[],
             });
             effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
+          } else if (observedStateContext) {
+            // No `x-telo-context` matched, so nothing was chain-validated here
+            // before. Validate the observed-state segment alone rather than
+            // merging the kernel globals, whose closed `variables` / `ports`
+            // nodes would newly reject reads that pass today.
+            effectiveContext = observedStateContext;
           }
 
           const engine = defaultRegistry().get(engineName);
@@ -1792,6 +1891,23 @@ export class StaticAnalyzer {
     // kind-instead-of-instance ref there is caught statically, not at runtime.
     diagnostics.push(...validateStepInvokeReferences(allManifests, defs, aliases));
 
+    // `required:` inside a `status:` block — reported here rather than by the
+    // AJV shape, which could only say "must NOT be valid" without naming the
+    // rule or the fix.
+    for (const issue of validateObservedStateDeclarations(allManifests)) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "OBSERVED_STATE_REQUIRED_FORBIDDEN",
+        source: SOURCE,
+        message: issue.message,
+        data: {
+          resource: { kind: issue.kind, name: issue.name },
+          filePath: issue.filePath,
+          path: "status.required",
+        },
+      });
+    }
+
     // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
     diagnostics.push(...validateExtends(allManifests, defs, aliases));
 
@@ -1841,7 +1957,13 @@ export class StaticAnalyzer {
     // 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.aliases, ctx.aliasesByModule, crossModuleTargets ?? []);
+    resolveRefSentinels(
+      normalized,
+      ctx.aliases,
+      ctx.aliasesByModule,
+      crossModuleTargets ?? [],
+      ctx.definitions!,
+    );
     // Canonicalize import-scoped schema `$ref`s (`telo://Self|Alias/Type`) so the
     // kernel that executes this output compiles inputs/outputs against the same
     // ids the type controllers register their schemas under.

package/src/builtins.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition } from "@telorun/sdk";
+import { OBSERVED_STATE_SCHEMA } from "./validate-observed-state.js";
 
 /** Descriptive provenance a module declares about itself, shared by
  *  `Telo.Application` and `Telo.Library`.
@@ -186,6 +187,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         },
         capability: { type: "string" },
         schema: { type: "object", additionalProperties: true },
+        status: OBSERVED_STATE_SCHEMA,
       },
       required: ["metadata"],
       // Telo.Abstract is an extension point by design — it must accept forward-compatible
@@ -214,6 +216,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
       type: "object",
       additionalProperties: true,
       properties: {
+        status: OBSERVED_STATE_SCHEMA,
         resources: {
           type: "array",
           items: {

package/src/extends-resolution.ts

@@ -2,8 +2,17 @@ import type { ResourceDefinition } from "@telorun/sdk";
 import { mergeTypeSchemas } from "@telorun/sdk";
 
 /** Resolves a kind string (canonical or alias form, depending on the caller's
- *  registry) to its `Telo.Definition` / `Telo.Abstract`, or undefined. */
-export type DefResolver = (kind: string) => ResourceDefinition | undefined;
+ *  registry) to its `Telo.Definition` / `Telo.Abstract`, or undefined.
+ *
+ *  `from` is the definition the kind was read off. An `extends` alias belongs to
+ *  the file that DECLARES the definition, not to whoever is reading it, so a
+ *  resolver that walks an inheritance chain across module boundaries must
+ *  re-scope at each hop — `from.metadata.module` is what it scopes to. Resolvers
+ *  that operate in a single scope ignore the parameter. */
+export type DefResolver = (
+  kind: string,
+  from?: ResourceDefinition,
+) => ResourceDefinition | undefined;
 
 /** The template-body / controller fields a definition may carry. Kept local
  *  because `ResourceDefinition` intentionally types only the stable surface;
@@ -19,6 +28,7 @@ interface DefinitionBody {
   resources?: unknown[];
   base?: Record<string, unknown>;
   schema?: Record<string, any>;
+  status?: Record<string, any>;
 }
 
 const body = (def: ResourceDefinition | undefined): DefinitionBody =>
@@ -32,7 +42,7 @@ export function resolveParent(
 ): ResourceDefinition | undefined {
   const ext = body(def).extends;
   if (typeof ext !== "string" || ext.length === 0) return undefined;
-  return resolve(ext);
+  return resolve(ext, def);
 }
 
 /** The `extends` ancestor chain, nearest-first, excluding `def` itself.
@@ -122,3 +132,27 @@ export function effectiveAuthorSchema(
   const parentSchema = effectiveAuthorSchema(parent, resolve);
   return mergeTypeSchemas([parentSchema, own]) as Record<string, any>;
 }
+
+/** The observed state a kind reports (`status:`), folded through `extends`:
+ *  - with `base:` present → the **parent's** effective status unchanged; the
+ *    child delegates to the parent's controller and *is* a parent instance, so
+ *    it publishes exactly what the parent publishes.
+ *  - without `base:` but with `extends` → `merge(parent-effective, own)`, so a
+ *    contract can mandate what its implementations report and an implementation
+ *    can add to it.
+ *  - no `extends` → the own block unchanged.
+ *  Undefined when nothing in the chain declares one — the signal that the kind
+ *  has not opted into typed `.status` reads. */
+export function effectiveStatusSchema(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): Record<string, any> | undefined {
+  const own = body(def).status;
+  const parent = resolveParent(def, resolve);
+  if (!parent) return own;
+  const parentStatus = effectiveStatusSchema(parent, resolve);
+  if (body(def).base) return parentStatus;
+  if (!parentStatus) return own;
+  if (!own) return parentStatus;
+  return mergeTypeSchemas([parentStatus, own]) as Record<string, any>;
+}

package/src/index.ts

@@ -24,10 +24,23 @@ export {
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  applyObservedStateNode,
+  buildObservedStateIndex,
+  buildObservedStateResourcesSchema,
+  collectRunReachableNames,
+  observedStateRead,
+  validateObservedStateDeclarations,
+  OBSERVED_STATE_SCHEMA,
+} from "./validate-observed-state.js";
+export type { AnalyzedResource, ObservedStateRead } from "./validate-observed-state.js";
+export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
+export type { ModuleScopes } from "./alias-resolver.js";
 export {
   ancestorChain,
   controllerBearingAncestor,
   effectiveAuthorSchema,
+  effectiveStatusSchema,
   hasOwnControllerOrTemplate,
   inheritedCapability,
   isInheritedDelegation,

package/src/kernel-globals.ts

@@ -1,5 +1,6 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { residualEntrySchemaMap } from "./residual-schema.js";
+import { applyObservedStateNode } from "./validate-observed-state.js";
 
 /**
  * Kernel global names available in every CEL evaluation context at runtime.
@@ -36,6 +37,11 @@ const SYSTEM_KINDS = new Set([
  */
 export function buildKernelGlobalsSchema(
   manifests: ResourceManifest[],
+  /** Every resource a CEL read can name, including scope-declared ones (see
+   *  `buildObservedStateIndex`). Kinds that declare a `status:` get a typed,
+   *  closed `status` node; every other resource node stays open, so no flat read
+   *  that passes today can start failing. */
+  resources?: ReadonlyMap<string, { kind: string; status?: Record<string, any> }>,
 ): Record<string, any> {
   const moduleManifest =
     (manifests.find((m) => m.kind === "Telo.Application") as
@@ -55,6 +61,20 @@ export function buildKernelGlobalsSchema(
       resourceProps[name] = { type: "object", additionalProperties: true };
     }
   }
+  // Scope-declared resources (a `Run.Sequence`'s `with:`) publish like any other
+  // now, so their names resolve too — inside the scope's regions, which is where
+  // the only expressions that can name them live.
+  for (const [key, entry] of resources ?? []) {
+    if (key.includes(".")) continue;
+    resourceProps[key] ??= { type: "object", additionalProperties: true };
+    if (entry.status) applyObservedStateNode(resourceProps, key, entry.status);
+  }
+  // Imports' exported instances publish two levels deep (`resources.<Alias>.<name>`);
+  // the alias node stays open so its other keys keep resolving.
+  for (const [key, entry] of resources ?? []) {
+    if (!key.includes(".") || !entry.status) continue;
+    applyObservedStateNode(resourceProps, key, entry.status);
+  }
 
   return {
     type: "object",

package/src/resolve-ref-sentinels.ts

@@ -1,8 +1,22 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
+import {
+  isScopeEntry,
+  resolveFieldEntries,
+  type ReferenceFieldMap,
+} from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
+/** The slice of the definition registry this pass needs: a kind's field map, from
+ *  which the `x-telo-scope` slots are read. */
+export interface ScopeFieldMapSource {
+  getFieldMapForKind(
+    kind: string,
+    aliases?: { resolveKind(k: string): string | undefined },
+  ): ReferenceFieldMap | undefined;
+}
+
 /** Resolved ref shape written in place of a `!ref` sentinel. `alias` is set only for
  *  cross-module references (resolved into an imported library's exported instance). */
 type ResolvedRef = { kind: string; name: string; alias?: string };
@@ -52,6 +66,10 @@ export function resolveRefSentinels(
   // pass — which loads the entry module only — can still resolve `!ref Alias.name` against
   // imported libraries' exported instances.
   crossModuleTargets: ResourceManifest[] = [],
+  /** Supplies each kind's `x-telo-scope` slots. Without it a scoped name cannot be
+   *  told from a module-level one, and a shadowed `!ref` resolves to the resource
+   *  it shadows — so both call sites pass it. */
+  defs?: ScopeFieldMapSource,
 ): void {
   const moduleOf = (r: ResourceManifest): string | undefined =>
     (r.metadata as { module?: string } | undefined)?.module;
@@ -109,21 +127,67 @@ export function resolveRefSentinels(
     return undefined;
   };
 
+  /** Names a resource declares in its own execution scopes, read from the kind's
+   *  `x-telo-scope` slots — the analyzer's single definition of "scope", shared
+   *  with `manifest-visitor`. Inferring it structurally instead (any array of
+   *  named inline manifests) would give scope-local shadowing to the first kind
+   *  that happens to carry such an array without asking for it, and this pass is
+   *  shared with the kernel, so the guess would be baked into the runtime tree
+   *  rather than merely reported. */
+  const declaredInScopes = (
+    resource: ResourceManifest,
+  ): Map<string, ResourceManifest> | undefined => {
+    const fieldMap = defs?.getFieldMapForKind(resource.kind, aliases);
+    if (!fieldMap) return undefined;
+    let declared: Map<string, ResourceManifest> | undefined;
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isScopeEntry(entry)) continue;
+      for (const { value } of resolveFieldEntries(resource, fieldPath)) {
+        for (const element of Array.isArray(value) ? value : [value]) {
+          if (!element || typeof element !== "object" || Array.isArray(element)) continue;
+          const manifest = element as ResourceManifest;
+          const name = (manifest.metadata as { name?: string } | undefined)?.name;
+          if (typeof manifest.kind === "string" && typeof name === "string") {
+            (declared ??= new Map()).set(name, manifest);
+          }
+        }
+      }
+    }
+    return declared;
+  };
+
   // Resolve every `!ref` sentinel in the tree; leave opaque tagged / precompiled
   // nodes (e.g. `!cel`) untouched and don't descend into them.
-  const walk = (value: unknown): unknown => {
+  //
+  // `scoped` carries the names the enclosing resource declares in its `x-telo-scope`
+  // slots, and they SHADOW the module-level ones — the order the runtime resolves
+  // in. Baking the module-level kind into a shadowed reference would label traces
+  // and `getRefIdentity` with a resource that never runs.
+  const walk = (value: unknown, scoped?: Map<string, ResourceManifest>): unknown => {
     if (isRefSentinel(value)) {
-      return resolveTarget(value.source) ?? value;
+      const source = value.source;
+      const bare = source.indexOf(".") === -1;
+      const shadow = bare ? scoped?.get(source) : undefined;
+      if (shadow) return { kind: shadow.kind as string, name: source };
+      return resolveTarget(source) ?? value;
     }
     if (value === null || typeof value !== "object") return value;
     if (isTaggedSentinel(value)) return value;
     if ((value as { __compiled?: unknown }).__compiled) return value;
     if (Array.isArray(value)) {
-      for (let i = 0; i < value.length; i++) value[i] = walk(value[i]);
+      for (let i = 0; i < value.length; i++) value[i] = walk(value[i], scoped);
       return value;
     }
     const obj = value as Record<string, unknown>;
-    for (const key of Object.keys(obj)) obj[key] = walk(obj[key]);
+    // A nested inline resource may declare scopes of its own (a `Run.Sequence`
+    // inside another sequence's `with:`). Collected before descending, so the
+    // declarations are visible to every region of the resource that declares
+    // them — a sequence's `with:` names resolve in its `targets:` and `steps:`
+    // alike, not only inside `with:` itself.
+    const declared =
+      typeof obj.kind === "string" ? declaredInScopes(obj as ResourceManifest) : undefined;
+    const inner = declared ? new Map([...(scoped ?? new Map()), ...declared]) : scoped;
+    for (const key of Object.keys(obj)) obj[key] = walk(obj[key], inner);
     return value;
   };
 

package/src/validate-cel-context.ts

@@ -323,18 +323,37 @@ export function resolveContextAnnotations(
       typeof ref.name === "string" &&
       subpath
     ) {
+      const segments = subpath.split("/");
       const refManifest = allManifests.find(
         (m) => m.kind === ref.kind && (m.metadata as any)?.name === ref.name,
       ) as Record<string, any> | undefined;
       if (refManifest) {
         const resolved = resolveTypeFieldToSchema(
-          navigatePath(refManifest, subpath.split("/")) as unknown,
+          navigatePath(refManifest, segments) as unknown,
           allManifests,
         );
         if (resolved && typeof resolved === "object") {
           return resolved;
         }
       }
+      // The instance declares nothing, so fall back to its KIND's declaration —
+      // the same layering `buildStepContextSchema` applies to `steps.<name>.result`,
+      // so a kind with one fixed output shape (declared once on its Telo.Definition)
+      // types the context, while a kind that exposes the field for per-instance
+      // narrowing keeps winning above.
+      if (defs) {
+        const canonical = aliases?.resolveKind(ref.kind) ?? ref.kind;
+        const def = defs.resolve(canonical) as Record<string, unknown> | undefined;
+        if (def) {
+          const resolved = resolveTypeFieldToSchema(
+            navigatePath(def, segments) as unknown,
+            allManifests,
+          );
+          if (resolved && typeof resolved === "object") {
+            return resolved;
+          }
+        }
+      }
     }
     // Fallback: open schema (no false errors when outputType is not declared)
     return { ...schema, additionalProperties: true };