@telorun/kernel 0.56.0 → 0.58.0

package/src/evaluation-context.ts

@@ -26,6 +26,11 @@ import {
 } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import { evalPathCovers } from "@telorun/analyzer";
+import {
+  acceptReportedStatus,
+  buildPublishedProps,
+  diagnoseObservedStateAccess,
+} from "./observed-state.js";
 
 export { resourceKey };
 
@@ -165,6 +170,70 @@ export function buildResolvedProperties(
  */
 const cancellationStore = new AsyncLocalStorage<InvokeContext>();
 
+/**
+ * Instances whose `run()` has been dispatched. Reporting observed state before
+ * this is an error (see observed-state.ts).
+ *
+ * Keyed on the instance rather than on `(context, name)` because the context
+ * that STARTS a resource is not always the one that OWNS it: an importer's
+ * `targets:` can name a library's exported instance, and the library's own
+ * `ctx.setStatus()` — publishing into the context where its name lives — has to
+ * see that it started.
+ */
+const startedInstances = new WeakSet<object>();
+
+/**
+ * The last observed state each instance reported. Sticky: it stays until the
+ * resource is torn down, so a dispatch that reports nothing leaves the previous
+ * reading in place — a listener's bound address does not stop being true between
+ * calls. Keyed by instance for the same reason as `startedInstances`, and
+ * because a scope's per-run instances are distinct by construction, which is
+ * what keeps two concurrent runs from observing each other's readings.
+ */
+const reportedStatus = new WeakMap<object, Record<string, unknown>>();
+
+/**
+ * Instances whose `run()` has RETURNED. A long-lived Service never appears here
+ * — its `run()` stays pending for the process lifetime — which is exactly the
+ * distinction the reader needs: a Runnable that finished and reported nothing
+ * for a field it declares is a producer defect, while a Service that is still
+ * coming up is ordering, and telling those apart is not something the reader
+ * can do from the manifest.
+ */
+const completedInstances = new WeakSet<object>();
+
+/**
+ * The published value for an instance the caller resolved itself, rather than
+ * one reached by name through a context's own `resourceInstances`. The
+ * cross-module export path uses it: an importer surfaces a library's exported
+ * instances under `resources.<Alias>.<name>`, which crosses the boundary
+ * without passing through the owner's `resources` map — and must still carry the
+ * reading the instance reported, under the same rules.
+ *
+ * `kind` is already canonical (`<module>.<Kind>`) on that path, so the resolver
+ * needs no alias table.
+ */
+export async function publishedPropsOf(
+  kind: string,
+  name: string,
+  instance: ResourceInstance,
+  getDefinition: ((kind: string) => ResourceDefinition | undefined) | undefined,
+): Promise<Record<string, unknown>> {
+  const snap =
+    typeof instance.snapshot === "function"
+      ? ((await Promise.resolve(instance.snapshot())) as Record<string, unknown> | undefined)
+      : undefined;
+  return buildPublishedProps(snap, {
+    kind,
+    name,
+    module: kind.split(".")[0],
+    statusSchema: getDefinition?.(kind)?.status,
+    status: reportedStatus.get(instance),
+    started: startedInstances.has(instance),
+    completed: completedInstances.has(instance),
+  });
+}
+
 /**
  * The ambient dispatch context, for §7.2's automatic trace correlation: a record
  * emitted inside an active span carries that span's ids without the controller
@@ -194,6 +263,14 @@ function compileWalker(value: unknown): Walker {
       } catch (error) {
         const expr = compiled.source ? `\${{ ${compiled.source} }}` : "unknown expression";
         const msg = error instanceof Error ? error.message : String(error);
+        // Reading observed state that was never reported is its own failure with
+        // its own remedy, so it does not degrade into a bare "No such key".
+        const observed = compiled.source
+          ? describeObservedStateFailure(compiled.source, ctx, msg)
+          : null;
+        if (observed) {
+          throw new RuntimeError("ERR_OBSERVED_STATE_UNAVAILABLE", `${expr}: ${observed}`);
+        }
         const hint = compiled.source ? describeFailedAccess(compiled.source, ctx, msg) : null;
         const suffix = hint ? `\n  ${hint}` : "";
         throw new Error(`Expression ${expr} failed: ${msg}${suffix}`);
@@ -334,8 +411,87 @@ export class EvaluationContext implements IEvaluationContext {
     return this._createInstance;
   }
 
-  /** Called after init() when a resource snapshot is available. Overridden by ModuleContext. */
-  protected onResourceSnapshotted(_name: string, _snap: Record<string, unknown>): void {}
+  /** Called after init() when a resource snapshot is available. Overridden by
+   *  ModuleContext, and by a scope child (which keeps its own per-run map). */
+  protected onResourceSnapshotted(name: string, snap: Record<string, unknown>): void {
+    this.snapshotSink?.(name, snap);
+  }
+
+  /** Where published snapshots go for a context that has no `resources` map of
+   *  its own — set by `createScopeHandle` on the per-run child so scope-local
+   *  resources publish like any other. */
+  protected snapshotSink: ((name: string, snap: Record<string, unknown>) => void) | undefined;
+
+  /** Record that an instance has started. Republished so a read that arrives
+   *  before the resource reports gets the "still running" message rather than
+   *  the "never started" one. */
+  private async markStarted(name: string, instance: ResourceInstance): Promise<void> {
+    if (startedInstances.has(instance)) return;
+    startedInstances.add(instance);
+    await this.publishSnapshot(name);
+  }
+
+  /**
+   * Record what a resource observed and republish. Validated against the kind's
+   * `status:` here, at the point the claim is made, so an invalid report names
+   * the call that made it rather than surfacing at some later publication.
+   *
+   * Replaces rather than merges: this is the resource's observed state now. A
+   * declared field this call omits reads as missing, which is the truth — a
+   * sometimes-absent field is declared nullable and reported as `null`.
+   */
+  async setResourceStatus(name: string, status: Record<string, unknown>): Promise<void> {
+    const entry = this.resourceInstances.get(name) ?? this.createdInstances.get(name);
+    if (!entry) return;
+    const kind = entry.resource.kind as string;
+    if (!startedInstances.has(entry.instance)) {
+      throw new RuntimeError(
+        "ERR_OBSERVED_STATE_BEFORE_START",
+        `${kind} '${name}' reported observed state before it started. init() performs no I/O, so there is nothing observed to report there — call setStatus() from run(), or from a handler it reaches.`,
+      );
+    }
+    reportedStatus.set(
+      entry.instance,
+      acceptReportedStatus(status, { kind, name, statusSchema: this.statusSchemaOf(kind) }),
+    );
+    await this.publishSnapshot(name);
+  }
+
+  /** The kind's effective `status:` — already folded through `extends` and
+   *  stamped onto the definition at registration, in the scope that DECLARED it
+   *  (`resource-definition-controller`). Only the kind's own alias is resolved
+   *  here, in the reading module's scope, which is where it was written. */
+  private statusSchemaOf(kind: string): Record<string, any> | undefined {
+    const def = this.getDefinition?.(this.resolveKindSafe(kind)) ?? this.getDefinition?.(kind);
+    return def?.status;
+  }
+
+  /**
+   * Re-read a resource's `snapshot()` and republish it, joined with whatever
+   * observed state the resource has reported. The single publication path — the
+   * post-init capture, the post-run publication, the post-invoke refresh and
+   * every `setStatus()` all land here.
+   */
+  async publishSnapshot(name: string): Promise<void> {
+    const entry = this.resourceInstances.get(name) ?? this.createdInstances.get(name);
+    if (!entry?.instance.snapshot) return;
+    const snap = (await Promise.resolve(entry.instance.snapshot())) as
+      | Record<string, unknown>
+      | undefined;
+    const kind = entry.resource.kind as string;
+    this.onResourceSnapshotted(
+      name,
+      buildPublishedProps(snap, {
+        kind,
+        name,
+        module: entry.resource.metadata?.module as string | undefined,
+        statusSchema: this.statusSchemaOf(kind),
+        status: reportedStatus.get(entry.instance),
+        started: startedInstances.has(entry.instance),
+        completed: completedInstances.has(entry.instance),
+      }),
+    );
+  }
 
   get context(): Record<string, unknown> {
     return this._context;
@@ -425,6 +581,7 @@ export class EvaluationContext implements IEvaluationContext {
       this.emit,
     );
     child.resolveImportedInstance = (alias, name) => this.resolveImportedInstance(alias, name);
+    child.kindResolver = (kind) => this.resolveKindSafe(kind);
     return this.spawnChild(child);
   }
 
@@ -528,10 +685,13 @@ export class EvaluationContext implements IEvaluationContext {
             );
           }
           if (instance.init) await instance.init(ctx);
-          if (instance.snapshot) {
-            const snap = await Promise.resolve(instance.snapshot());
-            this.onResourceSnapshotted(name, (snap as Record<string, unknown>) ?? {});
-          }
+          // Publish BEFORE registering: publication can fail (a kind returning
+          // the reserved `status` key without declaring it, a report that does
+          // not match `status:`), and a resource that failed must not be left
+          // reachable through `getInstance` / Phase 5 injection / teardown.
+          // `publishSnapshot` looks the instance up in `createdInstances` too,
+          // so it resolves fine from here.
+          await this.publishSnapshot(name);
           this.resourceInstances.set(name, { resource, instance });
           this.createdInstances.delete(name);
           errors.delete(name);
@@ -639,6 +799,18 @@ export class EvaluationContext implements IEvaluationContext {
             parent.emit,
           ),
         );
+        child.kindResolver = (kind) => parent.resolveKindSafe(kind);
+
+        // Per-run map of the scope's OWN resources. Fresh per run, so two
+        // concurrent runs of the same sequence never observe each other's.
+        // The enclosing module's map is layered in at read time, not copied
+        // here: `setResource` replaces `_resources` wholesale on every publish,
+        // so a snapshot taken at scope entry would go stale the moment an outer
+        // resource republished (a post-invoke refresh, a later boot target).
+        const scopeLocal = new Map<string, Record<string, unknown>>();
+        child.snapshotSink = (name, snap) => {
+          scopeLocal.set(name, snap);
+        };
 
         // Propagate injection hook: extend getInstance to also resolve parent singleton instances.
         if (parent.preInitHook) {
@@ -684,6 +856,22 @@ export class EvaluationContext implements IEvaluationContext {
                 `Resource '${name}' not found in scope or outer context. Available scoped: ${[...child.resourceInstances.keys()].join(", ")}`,
               );
             },
+            async run(name: string): Promise<void> {
+              // Through the child context's chokepoint, so a scope target is
+              // traced, records that it started, and publishes its snapshot —
+              // exactly like a boot target. A scope target is always a
+              // with-resource, so it lives in the child.
+              await child.run(name);
+            },
+            get resources(): Record<string, unknown> {
+              // Merged on read so the outer half stays live; scope-local names
+              // win, matching `getInstance`'s order so CEL and `!ref` agree.
+              const merged: Record<string, unknown> = {
+                ...((parent._context.resources as Record<string, unknown> | undefined) ?? {}),
+              };
+              for (const [name, snap] of scopeLocal) merged[name] = snap;
+              return merged;
+            },
           };
           return await fn(scope);
         } finally {
@@ -716,6 +904,13 @@ export class EvaluationContext implements IEvaluationContext {
 
     for (const [key, { resource, instance }] of this.teardownOrder()) {
       const label = `${resource.kind}.${resource.metadata.name}`;
+      // A reading belongs to the run that produced it. The WeakMap would drop it
+      // with the instance anyway; clearing here also covers an instance something
+      // else still holds, so a torn-down resource can never keep publishing what
+      // it observed in a previous life.
+      reportedStatus.delete(instance);
+      startedInstances.delete(instance);
+      completedInstances.delete(instance);
       try {
         if (instance.teardown) await instance.teardown();
       } catch (err) {
@@ -979,6 +1174,10 @@ export class EvaluationContext implements IEvaluationContext {
       // `run()` — side effects only, no outputs. Prefer `invoke()` when both
       // exist so a dual-capability instance (e.g. Run.Sequence) keeps invoke
       // semantics and returns its `steps`/`outputs`.
+      // A pure Runnable reached through an `invoke:` slot runs exactly as it
+      // would from a `targets:` list, so it starts here too — its observed state
+      // must not stay withheld just because the dispatch slot was a different one.
+      if (typeof instance.invoke !== "function") await this.markStarted(name, instance);
       const call = () =>
         typeof instance.invoke === "function"
           ? (instance.invoke as (i: any, c?: InvokeContext) => any)(inputs as any, invokeCtx)
@@ -986,6 +1185,7 @@ export class EvaluationContext implements IEvaluationContext {
       const outputs = await (invokeCtx === ambient
         ? call()
         : cancellationStore.run(invokeCtx, call));
+      if (typeof instance.invoke !== "function") completedInstances.add(instance);
       await this.emit(`${name}.Invoked`, span("end", "ok", { inputs, outputs }));
       return outputs;
     } catch (err) {
@@ -1047,9 +1247,15 @@ export class EvaluationContext implements IEvaluationContext {
    *  kind unchanged. A typed seam (overridden in `ModuleContext`), matching the
    *  `traceRootScope()` pattern, rather than reaching across the boundary. */
   protected resolveKindSafe(kind: string): string {
-    return kind;
+    return this.kindResolver?.(kind) ?? kind;
   }
 
+  /** Alias-kind resolver inherited from the context that spawned this one. A
+   *  scope / template child holds no import table of its own, but its resources
+   *  are written with the declaring module's aliases (`Observed.Listener`), so
+   *  definition lookups there have to go through the parent's table. */
+  kindResolver: ((kind: string) => string) | undefined;
+
   private capabilityOf(kind: string): string | undefined {
     const resolved = this.resolveKindSafe(kind);
     return this.getDefinition?.(resolved)?.capability ?? this.getDefinition?.(kind)?.capability;
@@ -1224,6 +1430,12 @@ export class EvaluationContext implements IEvaluationContext {
 
     if (tracing) await this.emit(`${name}.Running`, span("start", undefined, {}));
 
+    // Marked before the call, not after: a Service's `run()` stays pending for
+    // the process lifetime, and reporting what it discovered while listening is
+    // the whole point — `ctx.setStatus()` is an error until the resource counts
+    // as started, so this has to happen first.
+    await this.markStarted(name, instance);
+
     try {
       // Runnable: run inside the ALS scope so nested invokes inherit the token and
       // trace id (skip the redundant `run` when the token is already ambient).
@@ -1231,6 +1443,10 @@ export class EvaluationContext implements IEvaluationContext {
       // its long-lived async work does not capture this scope.
       const call = () => (instance.run as (c?: InvokeContext) => Promise<void>)(invokeCtx);
       await (isService || invokeCtx === ambient ? call() : cancellationStore.run(invokeCtx, call));
+      // A one-shot Runnable that discovered something during run() publishes it
+      // without an explicit call; a Service never reaches this until teardown.
+      completedInstances.add(instance);
+      await this.publishSnapshot(name);
       await this.emit(`${name}.Run`, span("end", "ok", {}));
     } catch (err) {
       if (isCancellationError(err)) {
@@ -1438,6 +1654,35 @@ export function describeFailedAccess(
   ctx: unknown,
   msg: string,
 ): string | null {
+  const failure = locateFailedAccess(source, ctx, msg);
+  if (!failure) return null;
+  return `at ${failure.walked}: ${describeMissingAccess(failure.container, failure.missingKey)}`;
+}
+
+/**
+ * The observed-state message for a failed access, or null when the failure has
+ * nothing to do with observed state (the caller then falls back to the generic
+ * enrichment above). See `observed-state.ts` for why "has not started" and
+ * "started but reported nothing" are two different messages.
+ */
+export function describeObservedStateFailure(
+  source: string,
+  ctx: unknown,
+  msg: string,
+): string | null {
+  const failure = locateFailedAccess(source, ctx, msg);
+  if (!failure) return null;
+  return diagnoseObservedStateAccess(failure.container, failure.missingKey);
+}
+
+/** Walk a dotted CEL access path against the activation and stop at the node
+ *  whose key was missing. Null when the error isn't a key-access failure, the
+ *  source isn't a plain access path, or the path doesn't match the activation. */
+function locateFailedAccess(
+  source: string,
+  ctx: unknown,
+  msg: string,
+): { container: unknown; missingKey: string; walked: string } | null {
   const m = /^No such key:\s*(\S+)/.exec(msg);
   if (!m) return null;
   const missingKey = m[1];
@@ -1463,7 +1708,7 @@ export function describeFailedAccess(
         !(tok.name in (current as Record<string, unknown>))
       ) {
         if (tok.name !== missingKey) return null;
-        return `at ${walked.join("")}: ${describeMissingAccess(current, missingKey)}`;
+        return { container: current, missingKey, walked: walked.join("") };
       }
       current = (current as Record<string, unknown>)[tok.name];
       walked.push("." + tok.name);

package/src/kernel.ts

@@ -1030,6 +1030,7 @@ export class Kernel implements IKernel {
     resource: ResourceManifest,
     args?: ParsedArgs,
     ownerPrefix = "",
+    owningContext?: IEvaluationContext,
   ): ResourceContext {
     return new ResourceContextImpl(
       this,
@@ -1042,6 +1043,7 @@ export class Kernel implements IKernel {
       this.stderr,
       args,
       ownerPrefix,
+      owningContext ?? moduleContext,
     );
   }
 
@@ -1189,6 +1191,9 @@ export class Kernel implements IKernel {
       processedResource,
       parsedArgs,
       evalContext.ownerPrefix,
+      // Snapshot publication targets the context that OWNS the instance — for a
+      // `with:`-scoped resource that is the per-run scope child, not the module.
+      evalContext,
     );
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;

package/src/manifest-schemas.ts

@@ -1,5 +1,8 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
+// One definition of the `status:` block's shape, shared with `telo check` — the
+// `required:` restriction is reported by the analyzer, which can name the fix.
+import { OBSERVED_STATE_SCHEMA } from "@telorun/analyzer";
 const Ajv = AjvModule.default ?? AjvModule;
 
 // Re-export the shared ResourceRef fragment from the templating package
@@ -74,6 +77,7 @@ const baseDefinition = {
     capability: { type: "string" },
     extends: { type: "string", pattern: EXTENDS_ALIAS_PATTERN },
     schema: { type: "object", additionalProperties: true },
+    status: OBSERVED_STATE_SCHEMA,
     controllers: { type: "array", items: { type: "string" } },
     throws: throwsSchema,
   },
@@ -157,6 +161,8 @@ export const ResourceAbstractSchema = {
     metadata: metadataSchema,
     capability: { type: "string" },
     schema: { type: "object", additionalProperties: true },
+    // A contract may mandate what its implementations report.
+    status: OBSERVED_STATE_SCHEMA,
   },
   not: {
     anyOf: [{ required: ["controllers"] }, { required: ["throws"] }],

package/src/module-context.ts

@@ -219,6 +219,21 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     this.setResource(name, snap);
   }
 
+  /**
+   * A cross-module exported instance has no entry of its own here — it surfaces
+   * under `resources.<alias>.<name>`, published by the `Telo.Import` that owns
+   * it. So republishing such a name means republishing that import, which is
+   * what makes an exported service's observed state readable once the IMPORTER's
+   * `targets:` starts it.
+   */
+  override async publishSnapshot(name: string): Promise<void> {
+    await super.publishSnapshot(name);
+    if (this.resourceInstances.has(name)) return;
+    for (const [alias, scope] of this.importedScopes) {
+      if (scope.names.has(name)) await super.publishSnapshot(alias);
+    }
+  }
+
   /**
    * Register an imported module under the given alias, gated to the kind names it
    * exports (its `exports.kinds`). Only listed kinds resolve; an empty list exports
@@ -493,11 +508,10 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     ctx?: InvokeContext,
   ): Promise<any> {
     const result = await super.invoke(kind, name, inputs, ctx);
-    const entry = this.resourceInstances.get(name);
-    if (entry && typeof (entry.instance as any).snapshot === "function") {
-      const snap = await Promise.resolve((entry.instance as any).snapshot());
-      this.setResource(name, snap as Record<string, unknown>);
-    }
+    // Same publication path as the post-init capture and `setStatus()`:
+    // one shape, one target, so a declared `status:` is a guarantee on every
+    // path rather than on some of them.
+    await this.publishSnapshot(name);
     return result;
   }
 

package/src/observed-state.ts

@@ -0,0 +1,210 @@
+import AjvModule from "ajv";
+import { detachSnapshotValue, OBSERVED_STATE_KEY, RuntimeError } from "@telorun/sdk";
+
+const Ajv = AjvModule.default ?? AjvModule;
+
+/**
+ * Publication of a resource's **observed state** — what it learns while running,
+ * as opposed to what its author configured.
+ *
+ * The two arrive by different routes and this module keeps them apart.
+ * Configured state is pulled from `snapshot()`; observed state is pushed through
+ * `ResourceContext.setStatus()`, validated against the kind's `status:`, and
+ * held by the kernel until the resource is torn down. Publication then joins
+ * them: the flat half at `resources.<name>.<field>`, the reported half at
+ * `resources.<name>.status.<field>`.
+ *
+ * Holding the reported value (rather than re-deriving it) is what makes the
+ * reading *sticky*: a resource that learned its address once does not stop
+ * knowing it because a later dispatch had nothing new to say.
+ *
+ * A non-enumerable {@link OBSERVED_STATE_INFO} marker rides along on the
+ * published objects so a failed CEL read can say *why* the value is missing —
+ * "has not started", "still running" and "finished and never reported it" need
+ * different actions from the reader. It is a Symbol, so no CEL member access
+ * can reach it.
+ */
+export const OBSERVED_STATE_INFO = Symbol("telo.observedState");
+
+export interface ObservedStateInfo {
+  /** The kind as written on the resource doc (`OAuthClient.RedirectListener`). */
+  kind: string;
+  name: string;
+  /** Owning module, named in the "defect in someone else's module" message. */
+  module?: string;
+  /** The fields the kind declares it reports. */
+  fields: string[];
+  /** True once the resource's `run()` has been dispatched. */
+  started: boolean;
+  /** True once its `run()` has RETURNED. Never true for a long-lived Service,
+   *  whose `run()` stays pending — which is what separates "still coming up"
+   *  from "finished and reported nothing". */
+  completed: boolean;
+}
+
+/** Read the marker off a published props / status object, if it carries one. */
+export function observedStateInfo(value: unknown): ObservedStateInfo | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  return (value as Record<symbol, ObservedStateInfo>)[OBSERVED_STATE_INFO];
+}
+
+function mark(target: Record<string, unknown>, info: ObservedStateInfo): void {
+  Object.defineProperty(target, OBSERVED_STATE_INFO, {
+    value: info,
+    enumerable: false,
+    configurable: true,
+  });
+}
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+// Compiling a status schema costs ~ms and a resource may report repeatedly, so
+// keep the validator keyed on the schema object it came from. The kind's folded
+// `status:` is stamped once at registration, so this hits.
+const validators = new WeakMap<object, ReturnType<typeof ajv.compile>>();
+
+function validatorFor(schema: Record<string, any>): ReturnType<typeof ajv.compile> {
+  let compiled = validators.get(schema);
+  if (!compiled) {
+    compiled = ajv.compile(schema);
+    validators.set(schema, compiled);
+  }
+  return compiled;
+}
+
+/** The field names a `status:` schema declares, in declaration order. */
+export function declaredStatusFields(schema: Record<string, any> | undefined): string[] {
+  const props = schema?.properties;
+  return props && typeof props === "object" ? Object.keys(props) : [];
+}
+
+/**
+ * Check a reported value against the kind's declared `status:` and detach it
+ * from the controller. Called by `setStatus`, so an invalid report is refused at
+ * the point it is made rather than at some later publication.
+ */
+export function acceptReportedStatus(
+  status: Record<string, unknown>,
+  opts: { kind: string; name: string; statusSchema?: Record<string, any> },
+): Record<string, unknown> {
+  if (!opts.statusSchema) {
+    throw new RuntimeError(
+      "ERR_OBSERVED_STATE_UNDECLARED",
+      `${opts.kind} '${opts.name}' reported observed state, but the kind declares no 'status:' block. Declare it on the Telo.Definition (or on an abstract it extends) naming the fields this kind reports.`,
+    );
+  }
+  const validate = validatorFor(opts.statusSchema);
+  if (!validate(status)) {
+    const detail = (validate.errors ?? [])
+      .map((e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}`)
+      .join("; ");
+    throw new RuntimeError(
+      "ERR_OBSERVED_STATE_INVALID",
+      `${opts.kind} '${opts.name}' reported observed state that does not match its declared 'status:': ${detail}`,
+    );
+  }
+  return detachSnapshotValue(status) as Record<string, unknown>;
+}
+
+export interface PublishOptions {
+  kind: string;
+  name: string;
+  module?: string;
+  /** The kind's effective `status:` (folded through `extends`), or undefined
+   *  when nothing in the chain declares one. */
+  statusSchema?: Record<string, any>;
+  /** The last value the resource reported, or undefined if it has reported
+   *  none. Already validated and detached by {@link acceptReportedStatus}. */
+  status?: Record<string, unknown>;
+  /** Whether the resource's `run()` has been dispatched. */
+  started: boolean;
+  /** Whether its `run()` has returned. */
+  completed: boolean;
+}
+
+/**
+ * Turn a `snapshot()` result plus the last reported status into the value
+ * published at `resources.<name>`.
+ *
+ * Throws `ERR_OBSERVED_STATE_KEY_COLLISION` when a kind that declares `status:`
+ * also returns a flat field of that name — the two would land on the same key,
+ * and silently letting one win is worse than refusing. A kind that declares no
+ * `status:` may use the name freely.
+ */
+export function buildPublishedProps(
+  snapshot: Record<string, unknown> | undefined,
+  opts: PublishOptions,
+): Record<string, unknown> {
+  const flat = (detachSnapshotValue(snapshot ?? {}) ?? {}) as Record<string, unknown>;
+
+  if (!opts.statusSchema) return flat;
+
+  if (OBSERVED_STATE_KEY in flat) {
+    throw new RuntimeError(
+      "ERR_OBSERVED_STATE_KEY_COLLISION",
+      `${opts.kind} '${opts.name}' returns a '${OBSERVED_STATE_KEY}' field from snapshot(), but the kind declares a 'status:' block, which publishes at that same key. Rename the snapshot field, or drop the 'status:' declaration if the value is configuration rather than something the resource observes.`,
+    );
+  }
+
+  const info: ObservedStateInfo = {
+    kind: opts.kind,
+    name: opts.name,
+    module: opts.module,
+    fields: declaredStatusFields(opts.statusSchema),
+    started: opts.started,
+    completed: opts.completed,
+  };
+  mark(flat, info);
+
+  // Absent until the resource reports — so a read before then lands on a
+  // message that says which of the three things went wrong, rather than on a
+  // placeholder indistinguishable from a real reading.
+  if (!opts.status) return flat;
+
+  const published: Record<string, unknown> = { ...opts.status };
+  mark(published, info);
+  flat[OBSERVED_STATE_KEY] = published;
+  return flat;
+}
+
+/**
+ * The message for a failed `resources.<name>.status…` read, or null when the
+ * failure has nothing to do with observed state.
+ *
+ * `container` is the value the access chain reached, `missingKey` the key that
+ * was not there. Each cause gets its own message because they need different
+ * actions from the reader, and the kernel — which records both whether the
+ * resource started and whether its `run()` returned — is the only party that
+ * can tell them apart:
+ *
+ *  - not started → order the `targets:` so it runs first;
+ *  - started, still running → the read raced a resource that is still coming up
+ *    (a Service binding asynchronously); reorder or read later;
+ *  - `run()` returned and it never reported → the producing module declares
+ *    something it does not report, and no edit here fixes that.
+ */
+export function diagnoseObservedStateAccess(
+  container: unknown,
+  missingKey: string,
+): string | null {
+  const info = observedStateInfo(container);
+  if (!info) return null;
+
+  if (missingKey === OBSERVED_STATE_KEY) {
+    if (!info.started) {
+      return `'${info.name}' reports ${formatFields(info.fields)} only while it is running, and it has not started yet. Read reported values where the call happens — a step's inputs:, a request's url, a route handler, or a returns: expression — and make sure '${info.name}' is listed in the targets: that runs before this value is read.`;
+    }
+    return info.completed
+      ? `'${info.name}' finished running without ever reporting its observed state, which ${info.kind} declares it reports (${formatFields(info.fields)}). This is a defect in the ${info.module ?? "producing"} module — it never called setStatus, and no change to this manifest will fix it.`
+      : `'${info.name}' has started but has not reported its observed state yet — it is still running, so this read raced it. Move the read after the point where '${info.name}' has reported.`;
+  }
+
+  if (info.fields.includes(missingKey)) {
+    return `'${info.name}' reported observed state without '${missingKey}', which ${info.kind} declares it reports. Every declared field is mandatory once the resource has run — this is a defect in the ${info.module ?? "producing"} module, and no change to this manifest will fix it.`;
+  }
+  return `'${info.name}' reports no '${missingKey}'. It reports ${formatFields(info.fields)}.`;
+}
+
+function formatFields(fields: string[]): string {
+  if (fields.length === 0) return "no observed state";
+  return fields.map((f) => `'${f}'`).join(", ");
+}