@telorun/analyzer 0.45.0 → 0.47.0

package/dist/resolve-ref-sentinels.js

@@ -1,4 +1,5 @@
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import { isScopeEntry, resolveFieldEntries, } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 /**
  * Rewrites every `!ref <name>` sentinel in each non-system resource's value tree
@@ -41,7 +42,11 @@ export function resolveRefSentinels(resources, aliases, aliasesByModule,
 // walked as sources). The kernel passes the analyzer-flattened set here so the runtime
 // pass — which loads the entry module only — can still resolve `!ref Alias.name` against
 // imported libraries' exported instances.
-crossModuleTargets = []) {
+crossModuleTargets = [], 
+/** 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) {
     const moduleOf = (r) => r.metadata?.module;
     // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
     // cross-module resolution targets only — never walked as local ref sources here.
@@ -96,11 +101,50 @@ crossModuleTargets = []) {
         }
         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) => {
+        const fieldMap = defs?.getFieldMapForKind(resource.kind, aliases);
+        if (!fieldMap)
+            return undefined;
+        let declared;
+        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;
+                    const name = manifest.metadata?.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) => {
+    //
+    // `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, scoped) => {
         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, name: source };
+            return resolveTarget(source) ?? value;
         }
         if (value === null || typeof value !== "object")
             return value;
@@ -110,12 +154,19 @@ crossModuleTargets = []) {
             return value;
         if (Array.isArray(value)) {
             for (let i = 0; i < value.length; i++)
-                value[i] = walk(value[i]);
+                value[i] = walk(value[i], scoped);
             return value;
         }
         const obj = value;
+        // 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) : undefined;
+        const inner = declared ? new Map([...(scoped ?? new Map()), ...declared]) : scoped;
         for (const key of Object.keys(obj))
-            obj[key] = walk(obj[key]);
+            obj[key] = walk(obj[key], inner);
         return value;
     };
     for (const r of resources) {

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA0CjC;AAuFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgHrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD;AAUD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CAqBxF"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA0CjC;AAuFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAmIrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD;AAUD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CAqBxF"}

package/dist/validate-cel-context.js

@@ -276,13 +276,29 @@ export function resolveContextAnnotations(schema, manifestItem, opts) {
             typeof ref.kind === "string" &&
             typeof ref.name === "string" &&
             subpath) {
+            const segments = subpath.split("/");
             const refManifest = allManifests.find((m) => m.kind === ref.kind && m.metadata?.name === ref.name);
             if (refManifest) {
-                const resolved = resolveTypeFieldToSchema(navigatePath(refManifest, subpath.split("/")), allManifests);
+                const resolved = resolveTypeFieldToSchema(navigatePath(refManifest, segments), 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);
+                if (def) {
+                    const resolved = resolveTypeFieldToSchema(navigatePath(def, segments), allManifests);
+                    if (resolved && typeof resolved === "object") {
+                        return resolved;
+                    }
+                }
+            }
         }
         // Fallback: open schema (no false errors when outputType is not declared)
         return { ...schema, additionalProperties: true };

package/dist/validate-observed-state.d.ts

@@ -0,0 +1,98 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { type ModuleScopes } from "./alias-resolver.js";
+/**
+ * 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 declare const OBSERVED_STATE_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+};
+/**
+ * `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 declare function validateObservedStateDeclarations(manifests: readonly ResourceManifest[]): Array<{
+    kind: string;
+    name: string;
+    filePath?: string;
+    message: string;
+}>;
+/** A CEL access into a resource's observed-state segment. */
+export interface ObservedStateRead {
+    /** Import alias, when the read crosses a module boundary
+     *  (`resources.<Alias>.<name>.status`). */
+    alias?: string;
+    /** Resource name. */
+    name: string;
+    /** The field read under `.status`, when the chain names one. */
+    field?: string;
+}
+/**
+ * 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 declare function observedStateRead(chain: readonly string[]): ObservedStateRead | 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 declare function collectRunReachableNames(manifests: readonly ResourceManifest[], defs: {
+    resolve(kind: string): ResourceDefinition | undefined;
+}, aliases?: {
+    resolveKind(kind: string): string | undefined;
+}): Set<string>;
+/** What a resource name resolves to for CEL purposes. `status` is present only
+ *  when the kind declares one; `scoped` marks a resource declared inside an
+ *  `x-telo-scope` slot, which resolves only within that scope's regions. */
+export interface AnalyzedResource {
+    kind: string;
+    status?: Record<string, any>;
+    scoped?: boolean;
+}
+/**
+ * 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 declare function buildObservedStateIndex(manifests: readonly ResourceManifest[], defs: {
+    resolve(kind: string): ResourceDefinition | undefined;
+}, aliases?: {
+    resolveKind(kind: string): string | undefined;
+    moduleForAlias?(alias: string): string | undefined;
+}, scopes?: ModuleScopes): Map<string, AnalyzedResource>;
+/** 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 declare function buildObservedStateResourcesSchema(index: ReadonlyMap<string, AnalyzedResource>, open: boolean): Record<string, any>;
+/**
+ * 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 declare function applyObservedStateNode(properties: Record<string, any>, key: string, status: Record<string, any>): void;
+//# sourceMappingURL=validate-observed-state.d.ts.map

package/dist/validate-observed-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-observed-state.d.ts","sourceRoot":"","sources":["../src/validate-observed-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAyBjF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;CAGjC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB3E;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC;+CAC2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,GAAG,SAAS,CAOzF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;CAAE,EAC/D,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,GAC1D,GAAG,CAAC,MAAM,CAAC,CAyBb;AAgDD;;4EAE4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;CAAE,EAC/D,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAAC,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,EAC/G,MAAM,CAAC,EAAE,YAAY,GACpB,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAsC/B;AAyDD;;;gDAGgD;AAChD,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC5C,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,IAAI,CAmBN"}

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/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA6dtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAmetB"}

package/dist/validate-references.js

@@ -254,8 +254,14 @@ export function validateReferences(resources, context) {
                 }
                 // Local reference (bare name or explicit `Self.`-qualified).
                 const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
-                const target = byName.get(localName) ??
-                    visibleScopeManifests.find((m) => m.metadata?.name === localName);
+                // Scope-local FIRST, enclosing module as the fallback — the order the
+                // runtime uses at every name-resolution site (`ScopeContext.getInstance`,
+                // `ResourceContext.resolveRef`, and the CEL `resources` layering). Module-first
+                // here would validate a shadowed name against the resource the kernel will
+                // never bind: a false pass when the outer kind fits and the scoped one does
+                // not, a false REFERENCE_KIND_MISMATCH when it is the other way round.
+                const target = visibleScopeManifests.find((m) => m.metadata?.name === localName) ??
+                    byName.get(localName);
                 if (!target) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.45.0",
+  "version": "0.47.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.59.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;
+}