@telorun/kernel 0.84.0 → 0.86.0

package/src/kernel.ts

@@ -3,12 +3,16 @@ import {
   authoredModuleMetadata,
   buildEvalPaths,
   collectZoneModuleDocuments,
+  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;
@@ -129,10 +143,6 @@ export interface KernelOptions {
    *  fails to dispatch). Order matters — later entries take priority over
    *  earlier ones (sources are unshifted onto the dispatch chain). */
   sources: ManifestSource[];
-  /** Base URL for the registry source. When unset, the `RegistrySource`
-   *  default applies. Callers (e.g. the CLI) are responsible for resolving
-   *  `TELO_REGISTRY_URL` or any other env-based fallback before passing. */
-  registryUrl?: string;
 }
 
 /**
@@ -176,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;
@@ -195,7 +223,6 @@ export class Kernel implements IKernel {
   readonly stderr: NodeJS.WritableStream;
   readonly env: Record<string, string | undefined>;
   readonly argv: string[];
-  readonly registryUrl: string | undefined;
   /** The sources this kernel was constructed with, kept so `ctx.runtime` can
    *  give a child manifest — or a static check of one — the same resolution
    *  chain this kernel runs on. The transports come from the registry and are
@@ -232,11 +259,10 @@ export class Kernel implements IKernel {
       return { traceId: ambient.traceId, spanId };
     });
     this.argv = options.argv ?? [];
-    this.registryUrl = options.registryUrl;
     // Resolution sources come from the transport registry, so a scheme-owning
     // transport (OCI, later S3) joins the loader's dispatch chain by being
     // registered — no source-chain edits here.
-    this.loader = new Loader(defaultTransportRegistry(this.registryUrl).sources(), {
+    this.loader = new Loader(defaultTransportRegistry().sources(), {
       celHandlers: nodeCelHandlers,
     });
     this.injectedSources = [...options.sources];
@@ -334,8 +360,8 @@ export class Kernel implements IKernel {
     // import-controller's independent re-resolution onto the winning source so a
     // sub-library importing a lower version loads the same controller/definition
     // the analyzer registered — never a second, colliding copy. Keyed by
-    // canonical URL; `canonicalize` maps a registry ref (returned verbatim by
-    // the loader) to the URL the graph walk already resolved it to.
+    // canonical URL; `canonicalize` maps a ref returned verbatim by the loader
+    // to the URL the graph walk already resolved it to.
     const overrides = this._loadedGraph?.overrides;
     if (overrides && overrides.size > 0) {
       const canonical = this.loader.canonicalize(resolved) ?? resolved;
@@ -460,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
@@ -596,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>,
@@ -673,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)) {
@@ -1064,7 +1367,7 @@ export class Kernel implements IKernel {
   private buildModuleArtifacts(graph: LoadedGraph, manifestsDir: string | undefined): void {
     this.moduleArtifacts.clear();
     this.siblingLibraries.clear();
-    const transports = defaultTransportRegistry(this.registryUrl);
+    const transports = defaultTransportRegistry();
     const entryDir = this._entryUrl ? resolveEntryDir(this._entryUrl) ?? "" : "";
     // The same pre-anchor root `LocalManifestCacheSource` falls back to. Layers
     // live beside the cached manifest, so both halves have to look in the same
@@ -1086,7 +1389,6 @@ export class Kernel implements IKernel {
         file.requestedUrl,
         file.source,
         entryDir,
-        this.registryUrl,
         manifestsDir,
         legacyDir,
       );

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -15,7 +15,6 @@ import { TransportRegistry, defaultTransportRegistry } from "../transports/trans
 import { findWorkspaceRoot } from "../workspace-marker.js";
 
 const CACHE_SUBDIR = ".telo/manifests";
-const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
 
 /** Verify that `candidate` resolves to a path under `root`. Returns the
  *  candidate path on success, `null` when any segment escapes the root.
@@ -33,8 +32,8 @@ function joinUnder(root: string, ...segments: string[]): string | null {
 
 /** Single source of truth for URL → cache path. Used identically by the
  *  reader (cache lookup) and writer (install-time persistence). For any
- *  given import ref — registry ref, direct registry URL, arbitrary HTTP, or
- *  `oci://` — both sides land on the same file: the owning transport supplies
+ *  given import ref — an HTTP(S) URL or an `oci://` ref — both sides land on
+ *  the same file: the owning transport supplies
  *  the coordinates and the analyzer's `manifestCacheKey` renders them, the same
  *  grammar the hub's static manifest bucket and the editor's read path use.
  *
@@ -80,8 +79,8 @@ export function legacyManifestsDirFallback(
 
 /**
  * Reads previously-cached manifest YAMLs from the resolved manifest cache. Sits
- * ahead of `RegistrySource` / `HttpSource` in the source chain — a hit makes boot
- * hermetic, a miss falls through to the network source unchanged.
+ * ahead of `HttpSource` in the source chain — a hit makes boot hermetic, a miss
+ * falls through to the network source unchanged.
  *
  * Populated by `writeManifestCache` at install time.
  *
@@ -90,7 +89,7 @@ export function legacyManifestsDirFallback(
  * costs only CPU when it goes cold; this one costs network, so without the
  * fallback the move to a workspace-anchored root would stop a hermetic setup from
  * booting — its `telo install` output stranded at the old path, with the failure
- * surfacing as a registry fetch on a machine that has no route to one. Read-only
+ * surfacing as a network fetch on a machine that has no route out. Read-only
  * and one directory deep: writes always go to the current root, so the old copy
  * ages out rather than being maintained.
  */
@@ -99,17 +98,13 @@ export class LocalManifestCacheSource implements ManifestSource {
   private readonly legacyRoot: string | null;
   private readonly transports: TransportRegistry;
 
-  constructor(
-    entryDir: string,
-    registryUrl: string = DEFAULT_REGISTRY_URL,
-    manifestsDir?: string,
-  ) {
+  constructor(entryDir: string, manifestsDir?: string) {
     // `manifestsDir` is the resolved manifest-cache directory threaded from a
     // single `resolveCacheRoot` (honours `TELO_CACHE_DIR`); when absent we fall
     // back to the entry-anchored default so library/test callers are unchanged.
     this.cacheRoot = manifestsDir ?? legacyManifestsDir(entryDir);
     this.legacyRoot = legacyManifestsDirFallback(entryDir, this.cacheRoot);
-    this.transports = defaultTransportRegistry(registryUrl);
+    this.transports = defaultTransportRegistry();
   }
 
   supports(url: string): boolean {
@@ -176,11 +171,10 @@ export class LocalManifestCacheSource implements ManifestSource {
 export function cachePathForCanonical(
   canonicalSource: string,
   entryDir: string,
-  registryUrl: string | undefined = DEFAULT_REGISTRY_URL,
   manifestsDir?: string,
 ): string | null {
   const cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
-  return cachePathForUrl(canonicalSource, cacheRoot, defaultTransportRegistry(registryUrl));
+  return cachePathForUrl(canonicalSource, cacheRoot, defaultTransportRegistry());
 }
 
 /**
@@ -198,7 +192,6 @@ export function cachePathForCanonical(
 export async function writeManifestCache(
   graph: LoadedGraph,
   entryDir: string,
-  registryUrl: string = DEFAULT_REGISTRY_URL,
   manifestsDir?: string,
 ): Promise<string[]> {
   const written: string[] = [];
@@ -210,7 +203,7 @@ export async function writeManifestCache(
       if (seen.has(file.source)) continue;
       seen.add(file.source);
 
-      const target = cachePathForCanonical(file.source, entryDir, registryUrl, manifestsDir);
+      const target = cachePathForCanonical(file.source, entryDir, manifestsDir);
       if (!target) continue;
 
       await fs.mkdir(path.dirname(target), { recursive: true });

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;
+}