@telorun/kernel 0.85.0 → 0.87.0

package/src/kernel.ts

@@ -2,13 +2,17 @@ import {
   AnalysisRegistry,
   authoredModuleMetadata,
   buildEvalPaths,
-  collectZoneModuleDocuments,
+  collectModuleDocuments,
+  declarationSignature,
+  diffManifests,
   flattenForAnalyzer,
   flattenLoadedModule,
   isModuleKind,
+  nodeIdFor,
   Loader,
   StaticAnalyzer,
   type DefResolver,
+  type DiffEntry,
   type LoadedGraph,
   type ManifestSource,
 } from "@telorun/analyzer";
@@ -47,6 +51,11 @@ import { KernelTracer } from "./tracing.js";
 import { KernelLogging, type LoggingManifestBlock } from "./logging/kernel-logging.js";
 import type { ScopeConfig } from "./logging/scope-config.js";
 import { formatSpanCounter } from "./logging/span-id.js";
+import {
+  graphFileSources,
+  modulesThatMoved,
+  type ReconcileOutcome,
+} from "./reconcile.js";
 import { ambientInvokeContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
@@ -118,6 +127,11 @@ function throwInvalidState(operation: string, reason: string): never {
   );
 }
 
+/** Docs that register a KIND. `DefinitionRegistry` only ever adds, so a change
+ *  to one of these cannot be reconciled into a running kernel — the previous
+ *  registration would survive it. */
+const DEFINITION_KINDS: ReadonlySet<string> = new Set(["Telo.Definition", "Telo.Abstract"]);
+
 export interface KernelOptions {
   stdin?: NodeJS.ReadableStream;
   stdout?: NodeJS.WritableStream;
@@ -172,6 +186,24 @@ export class Kernel implements IKernel {
    *  which module's library layer each resolves to. Rebuilt on every `load()`. */
   private readonly siblingLibraries = new Map<string, SiblingLibraryMap>();
   private _loadedGraph?: LoadedGraph;
+  /** Declaration signatures of the installed set, taken at load time — see
+   *  `ManifestDiffOptions.previousSignatures` for why they cannot be taken
+   *  later. */
+  private _declarationSignatures = new Map<string, string>();
+
+  /** Set while a reconciliation is in flight. Two overlapping calls would
+   *  interleave unwind, deregister and re-initialize on one context, and a watch
+   *  loop with fast saves is exactly the caller that would do it. */
+  private _reconciling = false;
+
+  /** The directories and cache policy `load()` produced with, replayed by
+   *  {@link reconcile} so a second production cannot differ from the first. */
+  private _produceOptions?: {
+    manifestsDir: string | undefined;
+    analysisDir: string | undefined;
+    writeCache: boolean;
+    analyzeOnly: boolean;
+  };
   // Lifecycle state — guards boot/runTargets/teardown/invoke transitions.
   // teardown() is the only idempotent method; everything else throws on misuse.
   private _bootCalled = false;
@@ -454,6 +486,263 @@ export class Kernel implements IKernel {
     // through spawnChild() to module imports and scoped handles.
     this.rootContext.getDefinition = (kind) => this.controllers.getDefinition(kind);
 
+    // Kept so `reconcile()` re-produces against the same directories and cache
+    // policy this load used — a second load resolving them again could differ.
+    this._produceOptions = { manifestsDir, analysisDir, writeCache, analyzeOnly: false };
+    const produced = await this.produceManifests(sourceUrl, {
+      manifestsDir,
+      analysisDir,
+      writeCache,
+      analyzeOnly: options?.analyzeOnly === true,
+    });
+    // `analyzeOnly` stops before instantiation, so there is nothing to install.
+    if (!produced) return;
+    this._declarationSignatures = produced.signatures;
+    this.installManifests(produced.manifests);
+  }
+
+  /**
+   * Re-read the entry and bring the running kernel into line with it, rebuilding
+   * only what changed.
+   *
+   * Three things decide what happens, in order, and each escalates rather than
+   * narrowing on a guess:
+   *
+   *  1. **A module other than the entry moved.** The kernel's runtime manifest
+   *     set is entry-only — an imported library's resources live in the child
+   *     context its `Telo.Import` owns — so a library edit is invisible to the
+   *     resource diff and cannot be narrowed here at all.
+   *  2. **A module doc changed.** `variables` / `secrets` / `ports` / `logging`
+   *     are resolved once for the whole application and read by anything, so a
+   *     change there has no bounded impact set.
+   *  3. **Otherwise**, the resources whose declarations moved are unwound
+   *     together with everything transitively holding them, re-registered, and
+   *     re-initialized. Everything else keeps running, its instances untouched.
+   *
+   * `restartRequired` is a REPORT, not a failure: the caller rebuilds the
+   * kernel, which is what it does for every edit today. Nothing has been
+   * unwound when it is set.
+   */
+  async reconcile(): Promise<ReconcileOutcome> {
+    if (this._isTornDown) throwInvalidState("reconcile", "kernel has been torn down");
+    if (!this._isBooted) throwInvalidState("reconcile", "boot() has not completed");
+    const entryUrl = this._entryUrl;
+    const previousGraph = this._loadedGraph;
+    const produceOptions = this._produceOptions;
+    if (!entryUrl || !previousGraph || !produceOptions) {
+      throwInvalidState("reconcile", "load() has not been called");
+    }
+    if (this._reconciling) {
+      throwInvalidState("reconcile", "a reconciliation is already in progress");
+    }
+    const previousManifests = this.staticManifests;
+    const previousSignatures = this._declarationSignatures;
+    this._reconciling = true;
+    try {
+      return await this.reconcileLocked(
+        entryUrl,
+        previousGraph,
+        produceOptions,
+        previousManifests,
+        previousSignatures,
+      );
+    } finally {
+      this._reconciling = false;
+    }
+  }
+
+  private async reconcileLocked(
+    entryUrl: string,
+    previousGraph: LoadedGraph,
+    produceOptions: NonNullable<Kernel["_produceOptions"]>,
+    previousManifests: ResourceManifest[],
+    previousSignatures: Map<string, string>,
+  ): Promise<ReconcileOutcome> {
+
+    // The loader memoizes a file's parse on the assumption its contents do not
+    // change underneath one Loader — precisely what a reload breaks — so every
+    // file the previous graph read is dropped before it is asked for again.
+    for (const source of graphFileSources(previousGraph)) this.loader.forget(source);
+
+    const produced = await this.produceManifests(entryUrl, produceOptions);
+    if (!produced) throwInvalidState("reconcile", "produced no manifests");
+
+    // `produceManifests` writes the kernel's static half as it goes — the graph,
+    // the flattened set, the module artifacts, the definition registry. Those
+    // writes describe manifests that are only INSTALLED further down, so every
+    // exit before that point puts them back: a caller told to restart would
+    // otherwise hold a kernel whose static half had already moved, and a second
+    // reconcile would diff the new set against itself and report no change
+    // while the live instances are still the originals.
+    const restoreProduced = (): void => {
+      this._loadedGraph = previousGraph;
+      this.staticManifests = previousManifests;
+      this._declarationSignatures = previousSignatures;
+    };
+    const halted = (reason: string): ReconcileOutcome => {
+      restoreProduced();
+      return { reinitialized: [], removed: [], restartRequired: reason };
+    };
+
+
+    const moved = modulesThatMoved(previousGraph, produced.graph);
+    if (moved.length > 0) {
+      return halted(`an imported module changed: ${moved.join(", ")}`);
+    }
+
+    const diff = diffManifests(previousManifests, produced.manifests, { previousSignatures });
+    if (diff.entries.length === 0) {
+      // Nothing to install, so the new record describes exactly what is already
+      // running — keep it rather than restoring, so the next diff compares
+      // against the freshest read of the same file.
+      return { reinitialized: [], removed: [] };
+    }
+
+    const movedDoc = diff.entries.find(
+      (entry: DiffEntry) => isModuleKind((entry.next ?? entry.previous)!.kind as string),
+    );
+    if (movedDoc) return halted("the application document changed");
+
+    // A kind registration is once per kernel: `DefinitionRegistry` only ever
+    // adds, so a deleted or edited `Telo.Definition` would leave the old kind
+    // registered and the running kernel enforcing a weaker contract than
+    // `telo check` does against the same file — a divergence nothing reports.
+    const movedKind = diff.entries.find((entry: DiffEntry) =>
+      DEFINITION_KINDS.has((entry.next ?? entry.previous)!.kind as string),
+    );
+    if (movedKind) return halted("a resource kind definition changed");
+
+    // Names rather than node ids from here on: the root context keys everything
+    // by the local name, and a manifest in this set is by definition the entry
+    // module's own.
+    const nameOf = (manifest: ResourceManifest): string => manifest.metadata.name as string;
+    const stale = diff.entries
+      .filter((entry: DiffEntry) => entry.change !== "added")
+      .map((entry: DiffEntry) => nameOf(entry.previous!));
+    // Closed under HOLDERS: a resource holding one of these has the live
+    // instance injected into its slot, so it cannot outlive the rebuild.
+    const { impacted, opaque } = this.rootContext.impactedBy(stale);
+
+    // A module document is a registered resource whose `targets:` and
+    // `logging.sinks` hold references, so it is a HOLDER of them and the closure
+    // reaches it whenever one of those moves. It is the one resource nothing
+    // here can rebuild: only `installManifests` re-applies what it carries —
+    // targets, module metadata, the resolved environment, logging — and
+    // unwinding it would report the application itself as a routine removal.
+    const impactedDoc = [...impacted].find((name) => {
+      const kind = this.rootContext.declaredManifestFor(name)?.kind as string | undefined;
+      return kind !== undefined && isModuleKind(kind);
+    });
+    if (impactedDoc) return halted("the application document is in the impact set");
+
+    if (opaque.length > 0) {
+      // Someone resolved these by name during initialization, so the set of
+      // holders is unknown and no closure over the declared edges is an answer.
+      return halted(`a resource is held through a by-name resolution: ${opaque.join(", ")}`);
+    }
+
+    // A resource that has been started is one nothing will start again: boot
+    // targets run once, and re-initializing a Service leaves it constructed and
+    // not listening while this call would report it as rebuilt.
+    const started = [...impacted].filter((name) => this.rootContext.wasStarted(name));
+    if (started.length > 0) return halted(`a running resource would be rebuilt: ${started.join(", ")}`);
+
+    // BEFORE the unwind: both are pure over the manifests plus the registry, so
+    // running them afterwards would turn a detectable condition — an invalid
+    // reference, a cycle the edit introduced — into a kernel whose resources are
+    // already gone.
+    const { diagnostics, order, cycleError } = this.analyzer.prepare(
+      produced.manifests,
+      this.registry,
+    );
+    if (diagnostics.length > 0) {
+      restoreProduced();
+      throw new RuntimeError(
+        "ERR_MANIFEST_VALIDATION_FAILED",
+        "Manifest validation failed",
+        diagnostics.map(staticDiagnosticToRuntime),
+      );
+    }
+    if (cycleError) {
+      restoreProduced();
+      throw new RuntimeError("ERR_CIRCULAR_DEPENDENCY", cycleError);
+    }
+
+    const surviving = new Map<string, ResourceManifest>();
+    for (const manifest of produced.manifests) {
+      if (!isModuleKind(manifest.kind as string)) surviving.set(nameOf(manifest), manifest);
+    }
+
+    await this.rootContext.unwindResources(impacted);
+    for (const name of impacted) this.rootContext.deregisterManifest(name);
+
+    const removed = [...impacted].filter((name) => !surviving.has(name));
+    const added = diff.entries
+      .filter((entry: DiffEntry) => entry.change === "added")
+      .map((entry: DiffEntry) => nameOf(entry.next!));
+    const reinitialized = [...new Set([...impacted, ...added])].filter((name) =>
+      surviving.has(name),
+    );
+    for (const name of reinitialized) this.rootContext.registerManifest(surviving.get(name)!);
+    // A survivor keeps its instance and its declaration, but the declaration
+    // object is the previous load's and carries that load's `sourceLine`. Swap
+    // in the fresh one so a diagnostic anchored on a resource nobody touched
+    // still points at the line it is on now.
+    const rebuilt = new Set(reinitialized);
+    for (const [name, manifest] of surviving) {
+      if (!rebuilt.has(name)) this.rootContext.refreshManifest(name, manifest);
+    }
+
+    // Re-open for another pass: a resource resolving a sibling that has not been
+    // rebuilt yet must get the deferral the init loop retries on. Closed in the
+    // `finally` so a failure cannot leave the context open, which would turn
+    // every later lookup into a deferral with no pass coming.
+    this.rootContext.reopenForInitialization();
+    try {
+      if (order) this.rootContext.setInitOrder(order);
+      await this.rootContext.initializeResources();
+    } catch (error) {
+      // The resources are already gone; there is no rollback to a state that no
+      // longer exists. Say so rather than letting the caller read a validation
+      // failure as though nothing had happened.
+      throw new RuntimeError(
+        "ERR_RECONCILE_FAILED",
+        `reconciliation failed after unwinding ${[...impacted].join(", ")} — the kernel is ` +
+          `degraded and must be rebuilt: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof RuntimeError ? error.diagnostics : undefined,
+      );
+    } finally {
+      this.rootContext.closeInitialization();
+    }
+
+    return { reinitialized, removed };
+  }
+
+  /**
+   * Everything between a URL and a set of manifests ready to install: load the
+   * graph, validate it, flatten it, and normalize inline resources.
+   *
+   * Split from {@link load} because it is the half that can run AGAIN. A
+   * reconciliation re-produces manifests against the same context to find what
+   * moved, where `load` also builds the context, the built-in definitions and
+   * the injection hooks — all of which exist once per kernel.
+   *
+   * Returns `undefined` under `analyzeOnly`, which deliberately stops before
+   * module instantiation and target wiring.
+   */
+  private async produceManifests(
+    sourceUrl: string,
+    opts: {
+      manifestsDir: string | undefined;
+      analysisDir: string | undefined;
+      writeCache: boolean;
+      analyzeOnly: boolean;
+    },
+  ): Promise<
+    | { graph: LoadedGraph; manifests: ResourceManifest[]; signatures: Map<string, string> }
+    | undefined
+  > {
+    const { manifestsDir, analysisDir, writeCache } = opts;
     // Static analysis pre-flight: validates schemas and invocation context compatibility.
     // All errors are fatal — kernel does not start if analysis fails.
     // `desugarImports` expands each module's inline `imports:` map into synthetic
@@ -558,7 +847,7 @@ export class Kernel implements IKernel {
       // export surface, never its internal dispatch chain.
       {
         skipValidation,
-        moduleDocuments: collectZoneModuleDocuments(analysisGraph),
+        moduleDocuments: collectModuleDocuments(analysisGraph),
         hostVersions: nodeHostVersions(),
       },
       this.registry,
@@ -590,7 +879,7 @@ export class Kernel implements IKernel {
     // before module instantiation / target wiring / application-env value
     // resolution — those need a running environment (e.g. session secrets) the
     // build does not have, and the runtime `load()` performs them anyway.
-    if (options?.analyzeOnly) {
+    if (opts.analyzeOnly) {
       if (rootModuleDoc?.kind === "Telo.Application") {
         precompileApplicationEnvSchemas(
           rootModuleDoc as Record<string, any>,
@@ -667,7 +956,27 @@ export class Kernel implements IKernel {
       staticManifests,
     );
     this.staticManifests = normalizedManifests;
+    // Signed HERE, while these are still declarations. Installing them hands
+    // the very same objects to the context, and resolving a reference writes a
+    // live instance into one — so a signature taken later is of something else.
+    const signatures = new Map<string, string>();
+    for (const manifest of normalizedManifests) {
+      signatures.set(nodeIdFor(manifest), declarationSignature(manifest));
+    }
+    return { graph: analysisGraph, manifests: normalizedManifests, signatures };
+  }
 
+  /**
+   * Install manifests into the root context: register each one, and apply what
+   * a module doc carries — boot targets, module metadata, the application's
+   * resolved environment and its logging configuration.
+   *
+   * The other half of the {@link load} split. A reconciliation registers only
+   * the declarations that moved, so it calls {@link EvaluationContext.registerManifest}
+   * itself rather than coming through here; what lives here is the whole-set
+   * install, which happens once.
+   */
+  private installManifests(normalizedManifests: ResourceManifest[]): void {
     let rootApplicationManifest: ResourceManifest | undefined;
     for (const manifest of normalizedManifests) {
       if (isModuleKind(manifest.kind)) {

package/src/module-context.ts

@@ -224,6 +224,23 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     this._rebuildContext();
   }
 
+  /**
+   * Drop a resource's published reading, so `resources.<name>` reads as absent.
+   *
+   * What makes an unwind observable to CEL. A compile-eval field is expanded at
+   * create time, so a reader rebuilt while its provider's OLD reading was still
+   * published would bake that stale value in and succeed — where on a fresh boot
+   * the same expansion finds nothing and defers until the provider is back. This
+   * is what makes the two agree.
+   */
+  override clearPublishedReading(name: string): void {
+    if (!(name in this._resources)) return;
+    const next = { ...this._resources };
+    delete next[name];
+    this._resources = next;
+    this._rebuildContext();
+  }
+
   setControllerPolicy(policy: ControllerPolicy | undefined): void {
     this._controllerPolicy = policy;
   }
@@ -458,7 +475,30 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     return this.importAliases.has(alias);
   }
 
-  getInstance(name: string): unknown {
+  /**
+   * The recording door — see the contract in `@telorun/sdk`.
+   *
+   * A resolution taken while this module is still initializing is recorded
+   * against the NAME, because that is all this context has: it is reached as
+   * `ctx.moduleContext`, which is shared by every resource of the module, so
+   * there is no caller to attribute the read to. Recording the target is enough
+   * for the only decision that depends on it — a resource somebody may be
+   * holding cannot be rebuilt on its own — and the escalation that follows is
+   * never worse than rebuilding the whole context, which is what happens today.
+   *
+   * `state !== "Initialized"` is the same discriminator the deferral below
+   * already turns on, and it is the right one: before that point a caller is
+   * running `create()` or `init()` and may keep what it gets, after it a caller
+   * is handling a dispatch and resolves again next time.
+   */
+  getInstance(name: string, declaredBy?: { kind: string; name: string }): unknown {
+    // `declaredBy` means the name came out of a declared ref slot, so the edge
+    // is in the manifest and the host can already see it.
+    if (!declaredBy && this.state !== "Initialized") this.recordOpaqueRead(name);
+    return this.lookupInstance(name);
+  }
+
+  private lookupInstance(name: string): unknown {
     const entry = this.resourceInstances.get(name);
     if (!entry) {
       // A name this module DID declare but that has no instance is never an

package/src/reconcile.ts

@@ -0,0 +1,83 @@
+/**
+ * The pure half of reconciliation: what a second load of the same entry changed,
+ * at the granularity of whole modules.
+ *
+ * The per-RESOURCE answer is the analyzer's (`diffManifests`), and it is exact.
+ * This is the coarser question that has to be asked first, because the kernel's
+ * runtime manifest set is entry-only: an imported library's resources live in
+ * the child context its `Telo.Import` owns and never appear in the set the
+ * resource diff walks. A library edit is therefore invisible to that diff, and
+ * would silently reconcile to "nothing changed".
+ *
+ * So the modules are compared by content, and anything moving outside the entry
+ * escalates rather than being narrowed. That is the same posture the opaque-read
+ * escalation takes: a fallback to rebuilding, which is what a host does today.
+ */
+import type { LoadedGraph, LoadedModule } from "@telorun/analyzer";
+
+/** What one {@link reconcile} pass did, or why it could not narrow. */
+export interface ReconcileOutcome {
+  /** Resources rebuilt: the declarations that moved, plus everything that was
+   *  holding one of them. */
+  readonly reinitialized: readonly string[];
+  /** Resources whose declaration is gone. Unwound, not replaced. */
+  readonly removed: readonly string[];
+  /** Set when the change had no bounded impact set and the caller must rebuild
+   *  the kernel. Nothing has been unwound when this is present. */
+  readonly restartRequired?: string;
+}
+
+/** Every file the graph read, so a caller can drop them from the loader's cache
+ *  before asking for them again. `Loader.loadFile` assumes a file's contents do
+ *  not change under one Loader, which is exactly the assumption a reload
+ *  breaks. */
+export function graphFileSources(graph: LoadedGraph): string[] {
+  const sources = new Set<string>();
+  for (const module of graph.modules.values()) {
+    sources.add(module.owner.source);
+    for (const partial of module.partials) sources.add(partial.source);
+  }
+  sources.add(graph.entry.owner.source);
+  for (const partial of graph.entry.partials) sources.add(partial.source);
+  return [...sources];
+}
+
+/** A module's content: every file it is made of, as text.
+ *
+ *  Compared as a string rather than hashed — there is no collision to reason
+ *  about, and a missed change here is a library that silently keeps running
+ *  against source it no longer matches. */
+function moduleSignature(module: LoadedModule): string {
+  return [module.owner, ...module.partials]
+    .map((file) => `${file.source}\u0000${file.text}`)
+    .join("\u0000\u0000");
+}
+
+/**
+ * Modules other than the entry whose content moved between two loads, including
+ * ones that appeared or disappeared.
+ *
+ * The entry is excluded because the resource diff answers for it precisely.
+ * Everything else is a library, whose resources this kernel cannot see
+ * individually.
+ */
+export function modulesThatMoved(previous: LoadedGraph, next: LoadedGraph): string[] {
+  const before = new Map<string, string>();
+  for (const [source, module] of previous.modules) {
+    if (source === previous.rootSource) continue;
+    before.set(source, moduleSignature(module));
+  }
+
+  const moved: string[] = [];
+  const seen = new Set<string>();
+  for (const [source, module] of next.modules) {
+    if (source === next.rootSource) continue;
+    seen.add(source);
+    const was = before.get(source);
+    if (was === undefined || was !== moduleSignature(module)) moved.push(source);
+  }
+  for (const source of before.keys()) {
+    if (!seen.has(source)) moved.push(source);
+  }
+  return moved;
+}

package/src/resource-edges.ts

@@ -0,0 +1,114 @@
+/**
+ * What the create-time reference edges tell us about a set of resources.
+ *
+ * The edges themselves are captured by `collectResourceRefs` and projected onto
+ * local names by `localDependencyNames` (both in `evaluation-context.ts`, beside
+ * the init loop that records them). This module is the two questions asked of
+ * that record afterwards, and they are the same question read in opposite
+ * directions:
+ *
+ *  - **Forward**, for teardown: in what order may these unwind, so that a
+ *    consumer's inverses run while what it holds is still alive.
+ *  - **Reverse**, for reconciliation: if these resources are about to become
+ *    invalid, who else is holding one and therefore becomes invalid too.
+ *
+ * Both read `Map<consumer, provider names>` and neither knows what a resource
+ * is, which is what keeps them testable without a kernel.
+ */
+
+/** A resource's outgoing edges: the local names it holds. */
+export type DependencyMap = ReadonlyMap<string, readonly string[]>;
+
+/**
+ * Order resources so that a consumer is torn down before everything it holds.
+ *
+ * The caller's order is the TIEBREAK, not the rule. Reverse insertion is
+ * already a valid reverse-topological order for every edge Phase-5 injection
+ * resolves, because the init loop defers a resource whose refs are unresolved
+ * (`ERR_LOCAL_REF_PENDING`) and so cannot insert a consumer before its
+ * provider. What this adds is the edges that never pass through injection — a
+ * controller resolving a sibling by name inside `init()` — where insertion
+ * order says nothing.
+ *
+ * A cycle emits the first unordered entry and continues: teardown must always
+ * run to completion, so an unorderable set degrades to the caller's order
+ * rather than raising.
+ */
+export function reverseTopologicalOrder<T>(
+  entries: ReadonlyArray<readonly [string, T]>,
+  nameOf: (value: T) => string,
+  dependenciesOf: (name: string) => readonly string[] | undefined,
+): Array<readonly [string, T]> {
+  const indexByName = new Map<string, number>();
+  entries.forEach(([, value], index) => indexByName.set(nameOf(value), index));
+
+  // One edge per (consumer, provider): the provider waits for the consumer.
+  const providersOf: number[][] = entries.map(() => []);
+  const waiting: number[] = entries.map(() => 0);
+  entries.forEach(([, value], consumer) => {
+    for (const dependency of dependenciesOf(nameOf(value)) ?? []) {
+      const provider = indexByName.get(dependency);
+      if (provider === undefined || provider === consumer) continue;
+      providersOf[consumer]!.push(provider);
+      waiting[provider]! += 1;
+    }
+  });
+
+  const ordered: Array<readonly [string, T]> = [];
+  const emitted: boolean[] = entries.map(() => false);
+  for (let count = 0; count < entries.length; count++) {
+    let pick = entries.findIndex((_, i) => !emitted[i] && waiting[i] === 0);
+    if (pick < 0) pick = entries.findIndex((_, i) => !emitted[i]);
+    emitted[pick] = true;
+    ordered.push(entries[pick]!);
+    for (const provider of providersOf[pick]!) waiting[provider]! -= 1;
+  }
+  return ordered;
+}
+
+/**
+ * Every resource that becomes invalid when `seeds` do: the seeds themselves, and
+ * everything that transitively HOLDS one of them.
+ *
+ * A holder has to go with what it holds because it is holding the instance
+ * itself — Phase-5 injection wrote a live object into its reference slot, and
+ * rebuilding the target leaves the holder pointing at an object nothing will
+ * ever call again. There is no version of this where the holder keeps running,
+ * which is why replacing one resource restarts everything above it. That is a
+ * cost to state rather than a defect to fix: editing a connection's declaration
+ * restarts what uses it.
+ *
+ * **Exact over the DECLARED edge set, and only that.** An edge exists here when
+ * a reference slot named the target, or when a CEL expression read it. A
+ * controller that resolves a sibling by NAME instead has a real dependency no
+ * walk of the manifest can see; those resolutions are recorded separately as
+ * they happen (`opaquelyRead`), and a caller whose closure reaches one has to
+ * escalate rather than trust this answer.
+ *
+ * A cycle is not a special case: the walk visits each name once.
+ */
+export function impactClosure(seeds: Iterable<string>, dependencies: DependencyMap): Set<string> {
+  // Reversed once per call rather than maintained: the map moves on every
+  // create, this is asked once per reconciliation, and an index kept in step
+  // with a mutating map is a second source of truth.
+  const holdersOf = new Map<string, string[]>();
+  for (const [consumer, providers] of dependencies) {
+    for (const provider of providers) {
+      const held = holdersOf.get(provider);
+      if (held) held.push(consumer);
+      else holdersOf.set(provider, [consumer]);
+    }
+  }
+
+  const impacted = new Set<string>();
+  const queue = [...seeds];
+  while (queue.length > 0) {
+    const name = queue.pop()!;
+    if (impacted.has(name)) continue;
+    impacted.add(name);
+    for (const holder of holdersOf.get(name) ?? []) {
+      if (!impacted.has(holder)) queue.push(holder);
+    }
+  }
+  return impacted;
+}

package/src/runtime-seam.ts

@@ -1,7 +1,7 @@
 import {
   Loader,
   StaticAnalyzer,
-  collectZoneModuleDocuments,
+  collectModuleDocuments,
   diagnosticFix,
   flattenForAnalyzer,
   remapMigratedPaths,
@@ -9,7 +9,7 @@ import {
   type DiagnosticData,
   type LoadedGraph,
   type ManifestSource,
-  type ZoneModuleDocuments,
+  type ModuleDocuments,
 } from "@telorun/analyzer";
 import {
   Stream,
@@ -235,7 +235,7 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     let parseDiagnostics: AnalysisDiagnostic[] = [];
     let versionDiagnostics: AnalysisDiagnostic[] = [];
     let migrationDiagnostics: AnalysisDiagnostic[] = [];
-    let moduleDocuments: ZoneModuleDocuments[] = [];
+    let moduleDocuments: ModuleDocuments[] = [];
     // Carried out of the try for the same reason the diagnostics are: analysis
     // runs over the MIGRATED tree while every path a caller resolves points at
     // the raw file, so the driver's provenance record has to be in hand below.
@@ -257,7 +257,7 @@ export class KernelRuntimeSeam implements RuntimeSeam {
       manifests = flattenForAnalyzer(graph);
       // The zone stage derives each imported library's export contracts from
       // its own full documents, which the flattened list drops.
-      moduleDocuments = collectZoneModuleDocuments(graph);
+      moduleDocuments = collectModuleDocuments(graph);
     } catch (err) {
       // A graph that would not load is an answer, not a failure of the call —
       // "this manifest does not load, and here is the reason" is precisely what