@telorun/analyzer 0.45.0 → 0.46.0

package/dist/validate-observed-state.js

@@ -0,0 +1,304 @@
+import { OBSERVED_STATE_KEY } from "@telorun/sdk";
+import { effectiveStatusSchema } from "./extends-resolution.js";
+import { parseExportEntry } from "./flatten-for-analyzer.js";
+import { moduleScopedDefResolver } from "./alias-resolver.js";
+import { buildReferenceFieldMap, isRefEntry, isScopeEntry, resolveFieldValues, } from "./reference-field-map.js";
+/** The kernel capabilities whose `run()` the kernel dispatches. A ref slot that
+ *  accepts one of them is a slot that can start a resource — `targets:` on an
+ *  Application or a `Run.Sequence`, and a step's `invoke:` (whose schema accepts
+ *  `Telo.Runnable` alongside `Telo.Invocable`, and which the kernel dispatches
+ *  through `run()` when the target has no `invoke()`). Keyed on the declared
+ *  capability, never on a field name or a kind, so any composer that accepts a
+ *  runnable participates without the analyzer knowing about it. */
+const RUN_DISPATCH_CONTRACTS = new Set(["Telo.Runnable", "Telo.Service"]);
+const SYSTEM_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Abstract",
+    "Telo.Import",
+    "Telo.Application",
+    "Telo.Library",
+]);
+/**
+ * The `status:` block's own schema — a plain JSON Schema, structurally. The one
+ * normative restriction (`required:` is rejected) is enforced by
+ * {@link validateObservedStateDeclarations} rather than here, so the author gets
+ * a message naming the rule and the fix instead of AJV's "must NOT be valid".
+ *
+ * Exported from the analyzer and re-used by the kernel's manifest schemas, so
+ * the rule has one definition rather than two kept in sync by hand.
+ */
+export const OBSERVED_STATE_SCHEMA = {
+    type: "object",
+    additionalProperties: true,
+};
+/**
+ * `required:` inside a `status:` block. Every declared field is mandatory once
+ * the resource has run, so the list would be either redundant or a lie; a
+ * genuinely sometimes-absent value is declared with a nullable type, which
+ * `CEL_NULLABLE_ACCESS` already guards.
+ */
+export function validateObservedStateDeclarations(manifests) {
+    const out = [];
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract")
+            continue;
+        const status = m.status;
+        if (!status || typeof status !== "object" || !Array.isArray(status.required))
+            continue;
+        const name = m.metadata?.name ?? "<unnamed>";
+        out.push({
+            kind: m.kind,
+            name,
+            filePath: m.metadata?.source,
+            message: `${m.kind}/${name}: 'status:' must not declare 'required:' — every field a kind declares ` +
+                `it reports is mandatory once the resource has run, so the list is either redundant or a ` +
+                `lie. Declare a sometimes-absent field with a nullable type instead ` +
+                `(e.g. type: [string, "null"]); CEL_NULLABLE_ACCESS then forces the reader to guard it.`,
+        });
+    }
+    return out;
+}
+/**
+ * Recognise an observed-state read in a member-access chain. Purely syntactic —
+ * it inspects the chain, not the topology — so the availability rule it feeds
+ * applies to every kind, declared or not.
+ *
+ * `resources.<name>.status.<field>` and the two-level cross-module form
+ * `resources.<Alias>.<name>.status.<field>` are both observed-state reads.
+ */
+export function observedStateRead(chain) {
+    if (chain[0] !== "resources")
+        return undefined;
+    if (chain[2] === OBSERVED_STATE_KEY)
+        return { name: chain[1], field: chain[3] };
+    if (chain[3] === OBSERVED_STATE_KEY) {
+        return { alias: chain[1], name: chain[2], field: chain[4] };
+    }
+    return undefined;
+}
+/**
+ * The names of every resource some slot can start: referenced from a ref slot
+ * that accepts a `Telo.Runnable` / `Telo.Service`, or named as a step's
+ * `invoke:` target. A resource in none of them can never `run()`, so it can
+ * never report observed state.
+ *
+ * Deliberately an over-approximation — a name reachable through any of these
+ * routes counts as runnable — because the cost of a false "can never run" is a
+ * valid manifest rejected, while the cost of a miss is only that the reader
+ * finds out at runtime instead, with a message that names the same fix.
+ */
+export function collectRunReachableNames(manifests, defs, aliases) {
+    const names = new Set();
+    const resolve = (kind) => defs.resolve(aliases?.resolveKind(kind) ?? kind) ?? defs.resolve(kind);
+    for (const manifest of manifests) {
+        const def = resolve(manifest.kind);
+        const schema = def?.schema;
+        if (!schema)
+            continue;
+        for (const [path, entry] of buildReferenceFieldMap(schema)) {
+            if (!isRefEntry(entry))
+                continue;
+            if (!entry.refs.some((ref) => RUN_DISPATCH_CONTRACTS.has(ref)))
+                continue;
+            for (const value of resolveFieldValues(manifest, path))
+                collectRefName(value, names);
+        }
+        // Step arrays nest through `if` / `while` / `switch` / `try`, and the step
+        // `invoke:` slot sits behind a local `$ref` the field map does not follow.
+        // Match the declared invoke key at any depth instead of re-deriving the
+        // nesting rules — over-approximating in the safe direction.
+        const invokeKey = stepInvokeKey(schema);
+        if (invokeKey)
+            collectKeyedRefs(manifest, invokeKey, names);
+    }
+    return names;
+}
+/** The property name a kind's `x-telo-step-context` declares as its dispatch
+ *  slot (`invoke`), or undefined when the kind has no step array. */
+function stepInvokeKey(schema) {
+    for (const fieldSchema of Object.values((schema.properties ?? {}))) {
+        const stepCtx = fieldSchema?.["x-telo-step-context"];
+        if (stepCtx?.invoke)
+            return stepCtx.invoke;
+    }
+    return undefined;
+}
+/** Collect ref names at every `key` property anywhere in `node`. */
+function collectKeyedRefs(node, key, out) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectKeyedRefs(item, key, out);
+        return;
+    }
+    if (node === null || typeof node !== "object")
+        return;
+    for (const [k, value] of Object.entries(node)) {
+        if (k === key)
+            collectRefName(value, out);
+        collectKeyedRefs(value, key, out);
+    }
+}
+/** Record the resource name a slot value points at — a resolved `{kind, name}`
+ *  ref, an unresolved `!ref` sentinel, or a `{ ref }` / `{ invoke }` wrapper. */
+function collectRefName(value, out) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefName(item, out);
+        return;
+    }
+    const v = value;
+    if (typeof v.name === "string")
+        out.add(v.name);
+    if (typeof v.source === "string") {
+        const dot = v.source.lastIndexOf(".");
+        out.add(dot >= 0 ? v.source.slice(dot + 1) : v.source);
+    }
+    for (const wrapper of ["ref", "invoke"]) {
+        if (v[wrapper] !== undefined)
+            collectRefName(v[wrapper], out);
+    }
+}
+/**
+ * Index every resource a CEL `resources.…` read can name: the module's own
+ * top-level resources, the ones declared inside `x-telo-scope` slots (a
+ * `Run.Sequence`'s `with:`), and each import's exported instances — keyed
+ * `<Alias>.<name>`, the two-level shape those publish under.
+ *
+ * Scope slots are found through the declaring kind's schema annotation, not by
+ * field name, so any composer with a scope participates.
+ */
+export function buildObservedStateIndex(manifests, defs, aliases, scopes) {
+    const out = new Map();
+    const resolve = moduleScopedDefResolver(defs, aliases, scopes);
+    /** `module` is the resource's DECLARING module: an exported instance is
+     *  written with that library's aliases (`kind: Self.Listener`), which the
+     *  consumer's table cannot resolve. */
+    const record = (kind, key, scoped, module) => {
+        const status = effectiveStatusSchema(resolve.in(kind, module), resolve);
+        out.set(key, { kind, ...(status ? { status } : {}), ...(scoped ? { scoped } : {}) });
+    };
+    for (const manifest of manifests) {
+        const kind = manifest.kind;
+        const name = manifest.metadata?.name;
+        if (!kind || SYSTEM_KINDS.has(kind))
+            continue;
+        if (name)
+            record(kind, name, false, manifest.metadata?.module);
+        const schema = resolve(kind)?.schema;
+        if (!schema)
+            continue;
+        for (const [path, entry] of buildReferenceFieldMap(schema)) {
+            if (!isScopeEntry(entry))
+                continue;
+            for (const value of resolveFieldValues(manifest, path)) {
+                for (const scopedEntry of Array.isArray(value) ? value : [value]) {
+                    const scopedKind = scopedEntry?.kind;
+                    const scopedName = scopedEntry?.metadata?.name;
+                    if (typeof scopedKind === "string" && typeof scopedName === "string") {
+                        record(scopedKind, scopedName, true);
+                    }
+                }
+            }
+        }
+    }
+    for (const [alias, name, kind, module] of importedExports(manifests, aliases)) {
+        record(kind, `${alias}.${name}`, false, module);
+    }
+    return out;
+}
+/**
+ * Every `<alias, exported name, kind>` an import makes readable as
+ * `resources.<Alias>.<name>`. The importer's `Telo.Import` docs give the
+ * aliases; the exported instances are the ones already stamped
+ * `metadata.forwardedExport` by `selectModuleManifestsForAnalysis` — the module
+ * doc that declared `exports.resources` is dropped for non-root modules, so the
+ * stamp, not the declaration, is what survives into the consumer's manifest
+ * list. A module doc is still consulted when one IS present (a single-library
+ * analysis, the editor's projection).
+ */
+function* importedExports(manifests, aliases) {
+    if (!aliases?.moduleForAlias)
+        return;
+    const declaredByModule = new Map();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Library")
+            continue;
+        const libName = (m.metadata?.name ?? m.metadata?.module);
+        const declared = m.exports?.resources;
+        if (!libName || !Array.isArray(declared))
+            continue;
+        declaredByModule.set(libName, new Set(declared
+            .filter((e) => typeof e === "string")
+            .map((e) => parseExportEntry(e).name)));
+    }
+    const exportsByModule = new Map();
+    for (const m of manifests) {
+        const module = m.metadata?.module;
+        const name = m.metadata?.name;
+        if (!module || !name || SYSTEM_KINDS.has(m.kind))
+            continue;
+        const forwarded = m.metadata?.forwardedExport;
+        if (!forwarded && !declaredByModule.get(module)?.has(name))
+            continue;
+        let byName = exportsByModule.get(module);
+        if (!byName)
+            exportsByModule.set(module, (byName = new Map()));
+        byName.set(name, m.kind);
+    }
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const alias = m.metadata?.name;
+        if (!alias)
+            continue;
+        const targetModule = aliases.moduleForAlias(alias);
+        const exported = targetModule && exportsByModule.get(targetModule);
+        if (!exported)
+            continue;
+        for (const [name, kind] of exported)
+            yield [alias, name, kind, targetModule];
+    }
+}
+/** The `resources` node of a CEL context schema: one entry per resource, each
+ *  open except for a typed, closed `status` node on kinds that declare one.
+ *  `open` keeps the map itself permissive, so unknown resource names and every
+ *  flat field pass exactly as they do today. */
+export function buildObservedStateResourcesSchema(index, open) {
+    const properties = {};
+    for (const [key, { status }] of index) {
+        if (!status)
+            continue;
+        applyObservedStateNode(properties, key, status);
+    }
+    return open
+        ? { type: "object", additionalProperties: true, properties }
+        : { type: "object", properties };
+}
+/**
+ * Write the typed `status` node for one index key into a `resources` property
+ * map. A dotted key (`Alias.name`) is an import's exported instance, which
+ * publishes two levels deep — the alias node stays open so every other name
+ * under it keeps resolving as it does today.
+ */
+export function applyObservedStateNode(properties, key, status) {
+    const dot = key.indexOf(".");
+    const leaf = {
+        type: "object",
+        additionalProperties: true,
+        properties: { [OBSERVED_STATE_KEY]: { ...status, additionalProperties: false } },
+    };
+    if (dot < 0) {
+        properties[key] = leaf;
+        return;
+    }
+    const alias = key.slice(0, dot);
+    const name = key.slice(dot + 1);
+    const aliasNode = (properties[alias] ??= {
+        type: "object",
+        additionalProperties: true,
+        properties: {},
+    });
+    (aliasNode.properties ??= {})[name] = leaf;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.56.0"
+    "@telorun/sdk": "0.58.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/alias-resolver.ts

@@ -121,3 +121,61 @@ export function scopeResolverForModule(
     ? aliasesByModule.get(ownModule)
     : undefined;
 }
+
+/** Per-declaring-module alias tables plus the set of root (consumer-owned)
+ *  modules. The shape `StaticAnalyzer.analyze` already threads through its
+ *  passes, and what {@link moduleScopedDefResolver} needs to re-scope. */
+export interface ModuleScopes {
+  aliasesByModule: ReadonlyMap<string, { resolveKind(kind: string): string | undefined }>;
+  rootModules: ReadonlySet<string>;
+}
+
+/** Minimal view of the definition registry a kind lookup needs. */
+export interface DefinitionLookup {
+  resolve(kind: string): unknown;
+}
+
+/**
+ * Resolve a kind to its definition **in the scope that declared it**.
+ *
+ * An `extends` alias belongs to the file it was written in, not to whoever is
+ * reading it: a consumer that imports only a backend (the sanctioned "one import
+ * instead of two") has no alias for the abstract's library, so folding an
+ * inheritance chain with the consumer's table silently stops at the first hop
+ * and yields an un-merged schema. `from` — the definition the kind was read off —
+ * carries `metadata.module`, which is the scope to resolve in; a chain crossing
+ * several modules re-scopes at every hop.
+ *
+ * `resolveIn` takes the module explicitly, for the top-level lookup where there
+ * is no `from` yet (an exported instance's `kind: Self.X` is written in the
+ * exporting library's scope, which the consumer's table cannot resolve either).
+ *
+ * The runtime counterpart is `resource-definition-controller`, which resolves
+ * against the defining module context and stamps the result; keeping both on the
+ * same rule is what stops `telo check` and the kernel from disagreeing about
+ * which inherited fields a child kind may set.
+ */
+export function moduleScopedDefResolver<T>(
+  defs: { resolve(kind: string): T | undefined },
+  aliases?: { resolveKind(kind: string): string | undefined },
+  scopes?: ModuleScopes,
+): {
+  (kind: string, from?: { metadata?: { module?: string } }): T | undefined;
+  in(kind: string, module?: string): T | undefined;
+} {
+  const resolveIn = (kind: string, module?: string): T | undefined => {
+    const scoped =
+      module && scopes && !scopes.rootModules.has(module)
+        ? scopes.aliasesByModule.get(module)
+        : undefined;
+    return (
+      (scoped ? defs.resolve(scoped.resolveKind(kind) ?? kind) : undefined) ??
+      defs.resolve(aliases?.resolveKind(kind) ?? kind) ??
+      defs.resolve(kind)
+    );
+  };
+  const resolver = ((kind: string, from?: { metadata?: { module?: string } }) =>
+    resolveIn(kind, from?.metadata?.module)) as ReturnType<typeof moduleScopedDefResolver<T>>;
+  resolver.in = resolveIn;
+  return resolver;
+}

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*\}\}/;
 
@@ -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));
 

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,