@telorun/kernel 0.79.0 → 0.81.0

package/src/kernel.ts

@@ -65,6 +65,7 @@ import {
 } from "./manifest-sources/analysis-stamp.js";
 import {
   cachePathForCanonical,
+  legacyManifestsDirFallback,
   resolveCacheRoot,
   resolveEntryDir,
 } from "./manifest-sources/local-manifest-cache-source.js";
@@ -421,19 +422,20 @@ export class Kernel implements IKernel {
       options?.cacheDir !== undefined ? options.cacheDir : resolveCacheRoot(sourceUrl);
     this._cacheRoot = cacheRoot;
     const manifestsDir = cacheRoot ? `${cacheRoot}/manifests` : undefined;
+    const analysisDir = cacheRoot ? `${cacheRoot}/analysis` : undefined;
     // `writeCache: false` (`telo run --no-cache-write`) keeps the cache
     // READ-only: compiled validators and the analysis stamp are still loaded
     // from disk, but never written back — so an ephemeral, read-only session
     // rootfs validates in-memory without touching the baked cache.
     const writeCache = options?.writeCache !== false;
     // Point the shared schema validator at the cache so compiled AJV validators
-    // are loaded (and, when writable, persisted) under
-    // `<cache-root>/manifests/__validators/`. Memory-/HTTP-rooted entries skip
-    // the cache; their schema compiles stay in-process only.
-    this.sharedSchemaValidator.setCacheDir(
-      manifestsDir ? `${manifestsDir}/__validators` : undefined,
-      { write: writeCache },
-    );
+    // are loaded (and, when writable, persisted) under `<cache-root>/validators/`.
+    // Beside `manifests/` rather than inside it: a compiled validator is not a
+    // cached module manifest. Memory-/HTTP-rooted entries skip the cache; their
+    // schema compiles stay in-process only.
+    this.sharedSchemaValidator.setCacheDir(cacheRoot ? `${cacheRoot}/validators` : undefined, {
+      write: writeCache,
+    });
     this.rootContext = new ModuleContext(
       sourceUrl,
       {},
@@ -551,9 +553,7 @@ export class Kernel implements IKernel {
     // passes are elided. Memory- / HTTP-rooted entries have no
     // local stamp store and always re-validate.
     const analysisSignature = computeAnalysisSignature(analysisGraph);
-    const stamp = manifestsDir
-      ? await readAnalysisStamp("", manifestsDir)
-      : undefined;
+    const stamp = analysisDir ? await readAnalysisStamp(sourceUrl, analysisDir) : undefined;
     const skipValidation = stamp?.signature === analysisSignature;
     const errors = this.analyzer.analyzeErrors(
       staticManifests,
@@ -574,13 +574,13 @@ export class Kernel implements IKernel {
         errors.map(staticDiagnosticToRuntime),
       );
     }
-    if (manifestsDir && writeCache && !skipValidation) {
+    if (analysisDir && writeCache && !skipValidation) {
       // Best-effort: stamp the verdict so subsequent loads hit the fast
       // path. A read-only filesystem (baked Docker image) reports the
       // failure on stderr and keeps running — the lookup above will
       // simply miss next time. Skipped under `--no-cache-write`.
       try {
-        await writeAnalysisStamp("", analysisSignature, manifestsDir);
+        await writeAnalysisStamp(sourceUrl, analysisSignature, analysisDir);
       } catch (err) {
         this.logging.kernelLogger().warn("analysis stamp write failed", undefined, { error: err });
       }
@@ -1017,8 +1017,12 @@ export class Kernel implements IKernel {
     return this._entryUrl;
   }
 
-  /** The npm install root for this load (`<cache-root>/npm`), threaded to the
-   *  controller loader so it doesn't re-derive it from the entry URL. */
+  /** The npm install BASE for this load (`<cache-root>/npm`), threaded to the
+   *  controller loader so it doesn't re-derive it from the entry URL. The base
+   *  holds one root per (entry path, host platform); the loader picks which one
+   *  this runner uses, so two runners over one workspace — a host and a
+   *  bind-mounting container — never share a tree whose `package.json` can only
+   *  be true for one of them. */
   getInstallRoot(): string | undefined {
     return this._cacheRoot ? `${this._cacheRoot}/npm` : undefined;
   }
@@ -1060,6 +1064,11 @@ export class Kernel implements IKernel {
     this.siblingLibraries.clear();
     const transports = defaultTransportRegistry(this.registryUrl);
     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
+    // place or an offline upgrade resolves a manifest from disk and then fetches
+    // its controllers.
+    const legacyDir = legacyManifestsDirFallback(entryDir, manifestsDir ?? null);
     // Parsed once per module and shared with the sibling-library join below: a
     // `telo.yaml` is a large multi-document file, and re-reading each target's
     // once per import edge put dozens of redundant full-YAML parses on the boot
@@ -1077,6 +1086,7 @@ export class Kernel implements IKernel {
         entryDir,
         this.registryUrl,
         manifestsDir,
+        legacyDir,
       );
       directories.set(file.source, moduleDir ?? undefined);
       const artifact = moduleArtifactFor({

package/src/manifest-sources/analysis-stamp.ts

@@ -7,19 +7,30 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 
 /**
- * Hash-keyed analysis cache: a tiny JSON sidecar in `.telo/manifests/`
+ * Hash-keyed analysis cache: a tiny JSON sidecar under `.telo/analysis/`
  * recording that an exact set of manifest bytes — under specific
  * `@telorun/kernel` and `@telorun/analyzer` package versions — passed
  * `analyzer.analyzeErrors`. The next `kernel.load` reads the sidecar
  * and, if signatures match, skips the per-resource validation walk.
  *
- * Lives next to the manifest cache (`LocalManifestCacheSource`) but is
- * independent of it — splitting both for grep-ability and because the
- * concerns (URL → file content vs. content → analyzer verdict) are
- * orthogonal.
+ * ONE STAMP PER ENTRY, in a directory keyed by a hash of the entry URL.
+ * A single file holding a single signature was per-app only because every app
+ * used to get its own `.telo` beside its manifest; once the cache root is shared
+ * across a workspace, one file means each app overwrites the last — A stamps, B
+ * misses and overwrites, forever. That is a permanent 100% miss with no error to
+ * show for it, worst in the test suite, where a kernel is spawned per manifest
+ * and the cache matters most.
+ *
+ * A DIRECTORY rather than several records in one file, because two kernels
+ * loading different manifests concurrently would otherwise read-modify-write the
+ * same JSON and lose each other's entry — and concurrent loads are the normal
+ * case, not the exception.
+ *
+ * NOT under `manifests/`, which holds cached module manifests keyed by transport.
+ * A verdict about an entry is not a manifest; filing it there made the directory
+ * mean two things.
  */
 
-const CACHE_SUBDIR = ".telo/manifests";
 
 /** File-format version of the analysis stamp envelope. Only bumped when
  *  the on-disk *layout* changes (new fields, restructured payload). The
@@ -30,7 +41,6 @@ const CACHE_SUBDIR = ".telo/manifests";
  *  disk. A hand-maintained integer for that purpose would silently mask
  *  newly-stricter validation until the next manifest edit. */
 const ANALYSIS_STAMP_FORMAT_VERSION = 1;
-const ANALYSIS_STAMP_FILE = `${CACHE_SUBDIR}/.validated.json`;
 
 const localRequire = createRequire(import.meta.url);
 
@@ -128,21 +138,33 @@ export function computeAnalysisSignature(graph: LoadedGraph): string {
     .digest("hex");
 }
 
-/** Read the stamped analysis verdict for the entry at `entryDir`, or
- *  `undefined` when missing / unreadable / format-mismatched. The
- *  `version` field is the on-disk *format* version; semantic
- *  invalidation flows through the signature (which embeds package
- *  versions). A future format change bumps `version` so older kernels
- *  reading a newer stamp (or vice versa) discard rather than misparse. */
+/** Where one entry's stamp lives: `<analysisDir>/<hash of entry URL>.json`.
+ *
+ *  Keyed by the entry URL rather than by its directory, because two manifests in
+ *  one directory (an app and its test harness) are two entries with two verdicts,
+ *  and a shared cache root makes the directory a far weaker discriminator than it
+ *  used to be. */
+function stampPath(analysisDir: string, entryUrl: string): string {
+  const id = createHash("sha256").update(entryUrl).digest("hex").slice(0, 32);
+  return path.join(analysisDir, `${id}.json`);
+}
+
+/** Read the stamped analysis verdict for `entryUrl`, or `undefined` when
+ *  missing / unreadable / format-mismatched. The `version` field is the
+ *  on-disk *format* version; semantic invalidation flows through the
+ *  signature (which embeds package versions). A future format change bumps
+ *  `version` so older kernels reading a newer stamp (or vice versa) discard
+ *  rather than misparse.
+ *
+ *  A pre-workspace-anchor `.telo/manifests/.validated.json` is simply never
+ *  looked at: it is a file where this layout wants a directory, so neither
+ *  version of the kernel can misread the other's. */
 export async function readAnalysisStamp(
-  entryDir: string,
-  manifestsDir?: string,
+  entryUrl: string,
+  analysisDir: string,
 ): Promise<AnalysisStamp | undefined> {
-  const stampPath = manifestsDir
-    ? path.join(manifestsDir, ".validated.json")
-    : path.join(entryDir, ANALYSIS_STAMP_FILE);
   try {
-    const text = await fs.readFile(stampPath, "utf-8");
+    const text = await fs.readFile(stampPath(analysisDir, entryUrl), "utf-8");
     const parsed = JSON.parse(text) as Partial<AnalysisStamp>;
     if (
       parsed?.version === ANALYSIS_STAMP_FORMAT_VERSION &&
@@ -160,17 +182,23 @@ export async function readAnalysisStamp(
  *  per-resource validation walk when the manifest set is unchanged.
  *  Idempotent; safe to call after every successful load. */
 export async function writeAnalysisStamp(
-  entryDir: string,
+  entryUrl: string,
   signature: string,
-  manifestsDir?: string,
+  analysisDir: string,
 ): Promise<void> {
   const stamp: AnalysisStamp = {
     version: ANALYSIS_STAMP_FORMAT_VERSION,
     signature,
   };
-  const target = manifestsDir
-    ? path.join(manifestsDir, ".validated.json")
-    : path.join(entryDir, ANALYSIS_STAMP_FILE);
+  const target = stampPath(analysisDir, entryUrl);
   await fs.mkdir(path.dirname(target), { recursive: true });
-  await fs.writeFile(target, JSON.stringify(stamp), "utf-8");
+  // Temp file + rename, as the controller-source cache does. Two kernels loading
+  // the SAME entry concurrently — the normal case for a shared root, where a test
+  // suite runs many manifests at once — would otherwise interleave writes to one
+  // path. A torn stamp is read as a miss rather than as a wrong verdict, so the
+  // cost is a silent re-validation, but rename makes it unrepresentable for the
+  // price of one syscall.
+  const tmp = `${target}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(stamp), "utf-8");
+  await fs.rename(tmp, target);
 }

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

@@ -12,6 +12,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 
 import { hostEnv } from "../host-env.js";
 import { TransportRegistry, defaultTransportRegistry } from "../transports/transport-registry.js";
+import { findWorkspaceRoot } from "../workspace-marker.js";
 
 const CACHE_SUBDIR = ".telo/manifests";
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
@@ -51,15 +52,51 @@ function cachePathForUrl(
   return joinUnder(cacheRoot, ...key.split("/"));
 }
 
+/** The PRE-WORKSPACE-ANCHOR manifest cache for an entry: always
+ *  `<entry-dir>/.telo/manifests`, regardless of marker or env override. `null`
+ *  for an entry with no local anchor.
+ *
+ *  A single definition because two things read the old location and they must
+ *  agree: the manifest source serves `telo.yaml` from it, and `moduleDirectoryFor`
+ *  places that module's LAYERS beside it. Deriving the path twice is how the two
+ *  halves end up disagreeing — the manifest resolving from the old root while its
+ *  controller layers are looked for under the new one, which is exactly the
+ *  offline boot the fallback exists to keep working. */
+export function legacyManifestsDir(entryDir: string): string | null {
+  return entryDir ? path.join(entryDir, CACHE_SUBDIR) : null;
+}
+
+/** `legacyManifestsDir`, or `null` when it would coincide with `current` — so the
+ *  fallback is never a second lookup at the same place. */
+export function legacyManifestsDirFallback(
+  entryDir: string,
+  current: string | null,
+): string | null {
+  const legacy = legacyManifestsDir(entryDir);
+  if (legacy === null) return null;
+  if (current !== null && path.resolve(legacy) === path.resolve(current)) return null;
+  return legacy;
+}
+
 /**
- * Reads previously-cached manifest YAMLs from `<entry-dir>/.telo/manifests/`.
- * Sits ahead of `RegistrySource` / `HttpSource` in the source chain — a hit
- * makes boot hermetic, a miss falls through to the network source unchanged.
+ * 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.
  *
  * Populated by `writeManifestCache` at install time.
+ *
+ * On a miss it consults the PRE-WORKSPACE-ANCHOR location
+ * (`<entry-dir>/.telo/manifests/`) before giving up. Every other cache in `.telo`
+ * 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
+ * and one directory deep: writes always go to the current root, so the old copy
+ * ages out rather than being maintained.
  */
 export class LocalManifestCacheSource implements ManifestSource {
-  private readonly cacheRoot: string;
+  private readonly cacheRoot: string | null;
+  private readonly legacyRoot: string | null;
   private readonly transports: TransportRegistry;
 
   constructor(
@@ -70,7 +107,8 @@ export class LocalManifestCacheSource implements ManifestSource {
     // `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 ?? path.join(entryDir, CACHE_SUBDIR);
+    this.cacheRoot = manifestsDir ?? legacyManifestsDir(entryDir);
+    this.legacyRoot = legacyManifestsDirFallback(entryDir, this.cacheRoot);
     this.transports = defaultTransportRegistry(registryUrl);
   }
 
@@ -108,7 +146,12 @@ export class LocalManifestCacheSource implements ManifestSource {
   }
 
   private tryMap(url: string): string | null {
-    const candidate = cachePathForUrl(url, this.cacheRoot, this.transports);
+    return this.tryMapIn(url, this.cacheRoot) ?? this.tryMapIn(url, this.legacyRoot);
+  }
+
+  private tryMapIn(url: string, root: string | null): string | null {
+    if (root === null) return null;
+    const candidate = cachePathForUrl(url, root, this.transports);
     if (!candidate) return null;
     // Require a regular file. A directory, dangling symlink, or stat failure
     // (ENOENT, EACCES, EISDIR-on-component) all fall through as a cache miss
@@ -219,18 +262,30 @@ export function resolveEntryDir(entryPath: string): string | null {
 }
 
 /** The single `.telo` cache root for an entry, resolved once and threaded to
- *  every consumer (manifest cache, compiled validators, analysis stamp, npm
- *  install root) so none of them re-derive it or read the env independently.
+ *  every consumer (manifest cache, compiled validators, analysis stamps, npm
+ *  install root, cargo target dirs) so none of them re-derive it or read the env
+ *  independently.
+ *
+ *  Precedence: `TELO_CACHE_DIR` (the relocated root a prebuilt image bakes its
+ *  deps into) wins; then the directory holding `telo-workspace.yaml`, so every
+ *  app in one repo shares a cache instead of each carrying its own copy of the
+ *  same manifests, validators, bundles and npm tree; then `<entry-dir>/.telo`.
+ *
+ *  Anchoring on the marker's LOCATION only — never its `modules:` list, which is
+ *  release scope — so a manifest in no release subtree (an example, a test
+ *  fixture) shares the cache exactly as an app does. With no marker anywhere
+ *  above, this collapses to what it did before the anchor existed, so the file
+ *  enables the shared cache rather than gating one and deleting it cannot break
+ *  a build.
  *
- *  `TELO_CACHE_DIR` (the relocated root a prebuilt image bakes its deps into)
- *  wins; otherwise the root sits beside the entry at `<entry-dir>/.telo`.
  *  Returns `null` for an entry with no local anchor — an http(s), `memory://`
  *  or any other non-`file:` scheme — in which case the disk cache is skipped.
- *  Consumers append the conventional subdirs: `manifests/`, `manifests/__validators/`,
- *  `npm/`. */
+ *  Consumers append the conventional subdirs: `manifests/`, `analysis/`,
+ *  `validators/`, `controller-src/`, `npm/`. */
 export function resolveCacheRoot(entryPath: string): string | null {
   const override = hostEnv().TELO_CACHE_DIR;
   if (override && override.trim()) return path.resolve(override.trim());
   const entryDir = resolveEntryDir(entryPath);
-  return entryDir ? path.join(entryDir, ".telo") : null;
+  if (!entryDir) return null;
+  return path.join(findWorkspaceRoot(entryDir) ?? entryDir, ".telo");
 }

package/src/runtime-seam.ts

@@ -176,7 +176,15 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     // child down in its own `finally`, so this only has to close the channels.
     const exitCode = (async () => {
       try {
-        await child.load(source);
+        // The child runs a manifest in the SAME workspace as its parent, so it
+        // shares the root the parent already resolved instead of deriving one
+        // beside the child manifest. Deriving put a `.telo` in every directory
+        // holding a test manifest and rebuilt every controller bundle once per
+        // test, since `Test.Suite` runs each test through here.
+        //
+        // `undefined` means "resolve one yourself" and `null` means "no cache" —
+        // a parent with no local anchor must yield the first, not the second.
+        await child.load(source, { cacheDir: this.kernel.getCacheRoot() ?? undefined });
         await child.start();
         return child.exitCode;
       } catch (err) {

package/src/workspace-marker.ts

@@ -0,0 +1,68 @@
+/**
+ * Finding `telo-workspace.yaml` on disk.
+ *
+ * Its LOCATION is a general anchor — the directory workspace-relative paths are
+ * measured from, the outer bound on how far a walk-up may look, and the root the
+ * `.telo` cache is anchored at — while its `modules:` list is release scope. So
+ * the finder is deliberately separate from `release/`: `telo run` bounds its
+ * `.env` collection with the marker and `resolveCacheRoot` anchors on it, and
+ * neither may reach into the release namespace to do so, where `loadWorkspace`
+ * (which parses `modules:` and throws when the file is absent) sits one import
+ * away.
+ *
+ * It lives in the KERNEL rather than the CLI because the cache root is resolved
+ * here, on a path a CLI-less embedder also takes (a child kernel started through
+ * the runtime seam, a test harness). The CLI re-exports it; nothing is duplicated.
+ *
+ * Parsing the file is the analyzer's (`release/workspace-config.ts`); finding it
+ * is the Node half, and this is all of it.
+ */
+
+import { WORKSPACE_FILENAME } from "@telorun/analyzer";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export { WORKSPACE_FILENAME };
+
+/**
+ * Walk up from `from` looking for the marker. Returns the directory holding it,
+ * or `undefined` — the file is optional. `telo release` requires one and reports
+ * its absence; `telo run` and `resolveCacheRoot` read `undefined` as "no parent
+ * lookup", falling back to what they did before the marker existed.
+ *
+ * `from` is resolved through symlinks first: a manifest reached through a linked
+ * directory would otherwise walk the LINK's parents, miss a marker that is right
+ * there in the real tree, and silently fall back to a narrower answer.
+ */
+export function findWorkspaceRoot(from: string): string | undefined {
+  let dir = realPath(path.resolve(from));
+  for (;;) {
+    if (isFile(path.join(dir, WORKSPACE_FILENAME))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** The marker must be a FILE. `existsSync` would accept a directory of that name
+ *  and anchor the whole cache on it, and the Rust half tests `is_file()` — a
+ *  workspace visible to one kernel and not the other is precisely the divergence
+ *  a shared marker exists to prevent. */
+function isFile(target: string): boolean {
+  try {
+    return fs.statSync(target).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** `fs.realpathSync`, falling back to the input when the path does not exist —
+ *  a manifest path that is wrong is the caller's error to report, not this
+ *  helper's to convert into a different one. */
+export function realPath(target: string): string {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return target;
+  }
+}