@telorun/analyzer 0.45.0 → 0.46.0

package/dist/alias-resolver.d.ts

@@ -65,4 +65,49 @@ export declare class AliasResolver {
  * the root `aliases`.
  */
 export declare function scopeResolverForModule(ownModule: string | undefined, rootModules: Set<string>, aliasesByModule: Map<string, AliasResolver>): AliasResolver | 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 declare 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;
+};
 //# sourceMappingURL=alias-resolver.d.ts.map

package/dist/alias-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alias-resolver.d.ts","sourceRoot":"","sources":["../src/alias-resolver.ts"],"names":[],"mappings":"AAAA;gFACgF;AAChF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE;;4FAEwF;IACxF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAE7D;;;;;0EAKsE;IACtE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAO5F;+FAC2F;IAC3F,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAI/D;sFACkF;IAClF,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAIhF;;;;qDAIiD;IACjD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD;;;;;;;;iFAQ6E;IAC7E,iBAAiB,CACf,IAAI,EAAE,MAAM,GAEV;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,GACvD;QAAE,MAAM,EAAE,SAAS,CAAA;KAAE;IAoBzB;8EAC0E;IAC1E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK7C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,YAAY,IAAI,MAAM,EAAE;IAIxB;;qEAEiE;IACjE,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE;CAO3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,aAAa,GAAG,SAAS,CAI3B"}
+{"version":3,"file":"alias-resolver.d.ts","sourceRoot":"","sources":["../src/alias-resolver.ts"],"names":[],"mappings":"AAAA;gFACgF;AAChF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE;;4FAEwF;IACxF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAE7D;;;;;0EAKsE;IACtE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAO5F;+FAC2F;IAC3F,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAI/D;sFACkF;IAClF,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAIhF;;;;qDAIiD;IACjD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD;;;;;;;;iFAQ6E;IAC7E,iBAAiB,CACf,IAAI,EAAE,MAAM,GAEV;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,GACvD;QAAE,MAAM,EAAE,SAAS,CAAA;KAAE;IAoBzB;8EAC0E;IAC1E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK7C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,YAAY,IAAI,MAAM,EAAE;IAIxB;;qEAEiE;IACjE,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE;CAO3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,aAAa,GAAG,SAAS,CAI3B;AAED;;0EAE0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IACxF,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,IAAI,EAAE;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;CAAE,EAC9C,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,EAC3D,MAAM,CAAC,EAAE,YAAY,GACpB;IACD,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,CAAC,GAAG,SAAS,CAAC;IACzE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAClD,CAgBA"}

package/dist/alias-resolver.js

@@ -107,3 +107,36 @@ export function scopeResolverForModule(ownModule, rootModules, aliasesByModule)
         ? aliasesByModule.get(ownModule)
         : undefined;
 }
+/**
+ * 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(defs, aliases, scopes) {
+    const resolveIn = (kind, module) => {
+        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, from) => resolveIn(kind, from?.metadata?.module));
+    resolver.in = resolveIn;
+    return resolver;
+}

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAsB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8xB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA07BvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AA6B9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAyyB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA4hCvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -1,4 +1,4 @@
-import { canonicalTypeSchemaId } from "@telorun/sdk";
+import { canonicalTypeSchemaId, OBSERVED_STATE_KEY } from "@telorun/sdk";
 import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver, scopeResolverForModule } from "./alias-resolver.js";
 import { buildCelEnvironment, buildImportInputCelEnvironment, buildTypedCelEnvironment, } from "./cel-environment.js";
@@ -6,6 +6,7 @@ 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";
@@ -19,7 +20,7 @@ import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity } from "./types.js";
-import { extractCelRegionScopes, extractContextsFromSchema, getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.js";
+import { extractAccessChains, extractCelRegionScopes, extractContextsFromSchema, getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.js";
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
@@ -601,6 +602,16 @@ function errorContextForPath(path, scopes) {
     }
     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, expr) {
+    try {
+        return extractAccessChains(env.parse(expr).ast);
+    }
+    catch {
+        return [];
+    }
+}
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 /** Recursively walk `data`+`schema` together, type-checking every pure CEL template
@@ -1100,9 +1111,34 @@ 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();
         // 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 = 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 }}`
         // resolves its nominal brand cross-doc.
@@ -1358,6 +1394,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 = [];
+        // The compile half alone: a field that resolves at startup, where observed
+        // state cannot exist yet.
+        let celCompilePaths = [];
         let celRegionScopes = [];
         let celRuleApplies = false;
         visitManifest(allManifests, defs, {
@@ -1382,10 +1421,15 @@ export class StaticAnalyzer {
                         ? buildEvalPaths(capabilityDef.schema)
                         : { 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 = [];
                 }
             },
@@ -1414,6 +1458,40 @@ 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 = e.contextSchema ?? celInvocationContext;
                 if (celStepContextSchema) {
                     const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
@@ -1452,6 +1530,13 @@ export class StaticAnalyzer {
                     });
                     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);
                 if (!engine) {
                     // No registered engine owns this tag — the expression would go
@@ -1515,6 +1600,22 @@ export class StaticAnalyzer {
         // 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));
+        // `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));
         diagnostics.push(...validateBaseMapping(allManifests, defs, aliases));

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AA2GvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA6nB/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AA4GvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA+nB/C,CAAC"}

package/dist/builtins.js

@@ -1,3 +1,4 @@
+import { OBSERVED_STATE_SCHEMA } from "./validate-observed-state.js";
 /** Descriptive provenance a module declares about itself, shared by
  *  `Telo.Application` and `Telo.Library`.
  *
@@ -177,6 +178,7 @@ export const KERNEL_BUILTINS = [
                 },
                 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
@@ -205,6 +207,7 @@ export const KERNEL_BUILTINS = [
             type: "object",
             additionalProperties: true,
             properties: {
+                status: OBSERVED_STATE_SCHEMA,
                 resources: {
                     type: "array",
                     items: {

package/dist/extends-resolution.d.ts

@@ -1,7 +1,13 @@
 import type { ResourceDefinition } 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 definition a given definition directly `extends`, or undefined when it
  *  extends nothing / the target can't be resolved. */
 export declare function resolveParent(def: ResourceDefinition | undefined, resolve: DefResolver): ResourceDefinition | undefined;
@@ -30,4 +36,15 @@ export declare function inheritedCapability(def: ResourceDefinition | undefined,
  *    `mergeTypeSchemas` that `Type.JsonSchema.extends` uses.
  *  - no `extends` → the own schema unchanged. */
 export declare function effectiveAuthorSchema(def: ResourceDefinition | undefined, resolve: DefResolver): 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 declare function effectiveStatusSchema(def: ResourceDefinition | undefined, resolve: DefResolver): Record<string, any> | undefined;
 //# sourceMappingURL=extends-resolution.d.ts.map

package/dist/extends-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extends-resolution.d.ts","sourceRoot":"","sources":["../src/extends-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;0EAC0E;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,kBAAkB,GAAG,SAAS,CAAC;AAqB3E;sDACsD;AACtD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAIhC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,EAAE,CAUtB;AAED;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAUvF;AAED;;mFAEmF;AACnF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAMhC;AAED;;sCAEsC;AACtC,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,OAAO,CAGT;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB"}
+{"version":3,"file":"extends-resolution.d.ts","sourceRoot":"","sources":["../src/extends-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;;;;;;;2DAO2D;AAC3D,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,kBAAkB,KACtB,kBAAkB,GAAG,SAAS,CAAC;AAsBpC;sDACsD;AACtD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAIhC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,EAAE,CAUtB;AAED;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAUvF;AAED;;mFAEmF;AACnF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAMhC;AAED;;sCAEsC;AACtC,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,OAAO,CAGT;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB;AAED;;;;;;;;;gDASgD;AAChD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CASjC"}

package/dist/extends-resolution.js

@@ -6,7 +6,7 @@ export function resolveParent(def, resolve) {
     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.
  *  Cycle-guarded so a malformed self/mutual `extends` can't loop forever. */
@@ -80,3 +80,27 @@ export function effectiveAuthorSchema(def, resolve) {
     const parentSchema = effectiveAuthorSchema(parent, resolve);
     return mergeTypeSchemas([parentSchema, own]);
 }
+/** 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, resolve) {
+    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]);
+}

package/dist/index.d.ts

@@ -5,7 +5,11 @@ export { importResolutionDiagnostics } from "./import-resolution-diagnostics.js"
 export type { GraphLoadError, ImportEdge, LoadedFile, LoadedGraph, LoadedModule, ParseError, } from "./loaded-types.js";
 export { flattenForAnalyzer, flattenLoadedModule, forwardReExportManifests, parseExportEntry, reExportSpecsFromExports, resolveExportedKinds, selectModuleManifestsForAnalysis, stampExportedKinds, stampReExportedKinds, type ParsedExportEntry, type ReExportSpec, } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
-export { ancestorChain, controllerBearingAncestor, effectiveAuthorSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, resolveParent, } from "./extends-resolution.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, resolveParent, } from "./extends-resolution.js";
 export type { DefResolver } from "./extends-resolution.js";
 export { hasIntermediateWildcard, parseRedactionPath, RedactionPathError, } from "./redaction-path.js";
 export type { RedactionSegment } from "./redaction-path.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -3,7 +3,9 @@ export { StaticAnalyzer } from "./analyzer.js";
 export { importResolutionDiagnostics } from "./import-resolution-diagnostics.js";
 export { flattenForAnalyzer, flattenLoadedModule, forwardReExportManifests, parseExportEntry, reExportSpecsFromExports, resolveExportedKinds, selectModuleManifestsForAnalysis, stampExportedKinds, stampReExportedKinds, } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
-export { ancestorChain, controllerBearingAncestor, effectiveAuthorSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, resolveParent, } from "./extends-resolution.js";
+export { applyObservedStateNode, buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, observedStateRead, validateObservedStateDeclarations, OBSERVED_STATE_SCHEMA, } from "./validate-observed-state.js";
+export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
+export { ancestorChain, controllerBearingAncestor, effectiveAuthorSchema, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, resolveParent, } from "./extends-resolution.js";
 export { hasIntermediateWildcard, parseRedactionPath, RedactionPathError, } from "./redaction-path.js";
 export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";
 export { visitManifest } from "./manifest-visitor.js";

package/dist/kernel-globals.d.ts

@@ -24,7 +24,15 @@ export declare const KERNEL_GLOBAL_NAMES: readonly ["variables", "secrets", "res
  *   the manifest list to a single library's file.
  * - `resources`: enumerates all non-system resource names
  */
-export declare function buildKernelGlobalsSchema(manifests: ResourceManifest[]): Record<string, any>;
+export declare 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>;
 /**
  * Merge kernel globals into an `x-telo-context` schema so chain-access
  * validation recognises `variables`, `secrets`, `resources`, `ports`

package/dist/kernel-globals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-globals.d.ts","sourceRoot":"","sources":["../src/kernel-globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,yDAA0D,CAAC;AAS3F;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiCrB;AA4CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB"}
+{"version":3,"file":"kernel-globals.d.ts","sourceRoot":"","sources":["../src/kernel-globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,yDAA0D,CAAC;AAS3F;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE;AAC7B;;;2CAG2C;AAC3C,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,GAC9E,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA+CrB;AA4CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB"}

package/dist/kernel-globals.js

@@ -1,4 +1,5 @@
 import { residualEntrySchemaMap } from "./residual-schema.js";
+import { applyObservedStateNode } from "./validate-observed-state.js";
 /**
  * Kernel global names available in every CEL evaluation context at runtime.
  * Both `buildKernelGlobalsSchema` (chain-access validation) and
@@ -30,7 +31,12 @@ const SYSTEM_KINDS = new Set([
  *   the manifest list to a single library's file.
  * - `resources`: enumerates all non-system resource names
  */
-export function buildKernelGlobalsSchema(manifests) {
+export function buildKernelGlobalsSchema(manifests, 
+/** 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) {
     const moduleManifest = manifests.find((m) => m.kind === "Telo.Application") ??
         manifests.find((m) => m.kind === "Telo.Library");
     const resourceProps = {};
@@ -44,6 +50,23 @@ export function buildKernelGlobalsSchema(manifests) {
             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",
         properties: {

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"}