@telorun/kernel 0.78.0 → 0.80.0

package/src/kernel.ts

@@ -17,6 +17,7 @@ import {
   type ContractValidatorFactory,
   resolveBoundContract,
 } from "./invocation-contract-binding.js";
+import { readProjectionRef, type ProjectionScope } from "@telorun/analyzer";
 import {
   ControllerContext,
   ControllerPolicy,
@@ -26,6 +27,7 @@ import {
   ResourceDefinition,
   ResourceInstance,
   ResourceManifest,
+  stampRefIdentity,
   RuntimeError,
   RuntimeEvent,
   type BootTarget,
@@ -49,6 +51,7 @@ import { ambientInvokeContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
 import { mintResourceHandle } from "./resource-handle.js";
+import { declarationOfInstance, recordInstanceDeclaration } from "./instance-declaration.js";
 import { nodeHostVersions } from "./host-versions.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
@@ -62,6 +65,7 @@ import {
 } from "./manifest-sources/analysis-stamp.js";
 import {
   cachePathForCanonical,
+  legacyManifestsDirFallback,
   resolveCacheRoot,
   resolveEntryDir,
 } from "./manifest-sources/local-manifest-cache-source.js";
@@ -418,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,
       {},
@@ -548,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,
@@ -571,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 });
       }
@@ -1057,6 +1060,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
@@ -1074,6 +1082,7 @@ export class Kernel implements IKernel {
         entryDir,
         this.registryUrl,
         manifestsDir,
+        legacyDir,
       );
       directories.set(file.source, moduleDir ?? undefined);
       const artifact = moduleArtifactFor({
@@ -1417,6 +1426,18 @@ export class Kernel implements IKernel {
       resolvedKind,
       (processedResource.metadata?.name as string | undefined) ?? "<unnamed>",
     );
+    recordInstanceDeclaration(instance, processedResource);
+    // Stamp the DECLARATION SITE here rather than at Phase-5 injection, because
+    // this is the only point where the instance and the context that declared it
+    // are both in hand: injection sees the consumer's context, not the target's,
+    // so a module stamped there would be whoever referenced it. Without it a
+    // durable step could not name its target anywhere the instance does not
+    // exist — the whole reason `step()` takes an identity at all.
+    const originPointer = originPointerOf(processedResource);
+    stampRefIdentity(instance, resolvedKind, processedResource.metadata?.name ?? "<unnamed>", {
+      ...(moduleCtx?.source ? { module: moduleCtx.source } : {}),
+      ...(originPointer === undefined ? {} : { pointer: originPointer }),
+    });
     (ctx as ResourceContextImpl).bindResourceIdentity(handle, resolvedKind, processedResource);
 
     // Bind the resolved invocation contract to the instance, here at the kernel's
@@ -1491,8 +1512,43 @@ export class Kernel implements IKernel {
     const resolveDef: DefResolver = (kind, from) =>
       this.registry.resolveDefinitionIn(kind, from?.metadata?.module);
 
-    const input = resolveBoundContract("inputType", resource, definition, resolveDef, factory);
-    const output = resolveBoundContract("outputType", resource, definition, resolveDef, factory);
+    // A DECLARATION-derived slot is resolved against the context that OWNS this
+    // resource, so a bare name means the same thing here as it does to `!ref`
+    // and to CEL — scope-local first, enclosing module as the fallback — and an
+    // alias routes into that import's exported instances.
+    const projections: ProjectionScope = {
+      resolveDefinition: (kind) =>
+        this.controllers.getDefinition(kind) as unknown as Record<string, any> | undefined,
+      // The slot holds the LIVE INSTANCE by now — Phase-5 injection runs before
+      // create — so the declaration is recovered by instance identity. The ref
+      // shape is still accepted, because a ref slot on a `with:`-scoped resource
+      // is not an injection site and reaches the controller unresolved.
+      resolveManifest: (value) => {
+        const injected = declarationOfInstance(value);
+        if (injected) return { manifest: injected as unknown as Record<string, any> };
+        const ref = readProjectionRef(value);
+        if (!ref) return undefined;
+        const found = impl.resolveDeclaredManifest(ref.name, ref.alias);
+        return found ? { manifest: found as unknown as Record<string, any> } : undefined;
+      },
+    };
+
+    const input = resolveBoundContract(
+      "inputType",
+      resource,
+      definition,
+      resolveDef,
+      factory,
+      projections,
+    );
+    const output = resolveBoundContract(
+      "outputType",
+      resource,
+      definition,
+      resolveDef,
+      factory,
+      projections,
+    );
     if (!input && !output) return;
 
     bindContract(instance, {
@@ -1576,3 +1632,28 @@ export class Kernel implements IKernel {
     );
   }
 }
+
+/**
+ * The JSON pointer to an inline declaration, from the origin the loader stamped.
+ *
+ * `xTeloOrigin.pathFromParent` is a dotted path with `[N]` indices — the loader's
+ * own spelling, which addresses the manifest tree and nothing else. A pointer is
+ * what crosses a boundary, so the conversion happens here rather than being left
+ * to each recipient to reinvent: segments are identifiers and indices, so the
+ * rewrite is mechanical and total.
+ */
+function originPointerOf(resource: ResourceManifest): string | undefined {
+  const origin = resource.metadata?.xTeloOrigin as
+    | { parentName?: unknown; pathFromParent?: unknown }
+    | undefined;
+  if (typeof origin?.parentName !== "string" || typeof origin.pathFromParent !== "string") {
+    return undefined;
+  }
+  const pointer = origin.pathFromParent
+    .replace(/\[(\d+)\]/g, ".$1")
+    .split(".")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1"))
+    .join("/");
+  return `${origin.parentName}#/${pointer}`;
+}

package/src/manifest-schemas.ts

@@ -22,6 +22,7 @@ export {
   manifestFragmentRef,
   ResourceRefSchema,
   RetryPolicySchema,
+  StepSchema,
   withSchemaFragments,
 } from "@telorun/analyzer";
 

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/module-context.ts

@@ -15,6 +15,7 @@ import type {
   InvokeStepContext,
   ModuleContext as IModuleContext,
   ResourceInstance,
+  ResourceManifest,
 } from "@telorun/sdk";
 import type { EmitEvent, InstanceFactory } from "@telorun/sdk";
 import { EvaluationContext } from "./evaluation-context.js";
@@ -106,7 +107,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       names: Set<string>;
       terminal: (
         name: string,
-      ) => (() => { kind: string; instance: ResourceInstance } | undefined) | undefined;
+      ) =>
+        | (() =>
+            | { kind: string; instance: ResourceInstance; manifest?: ResourceManifest }
+            | undefined)
+        | undefined;
     }
   >();
 
@@ -292,7 +297,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     names: string[],
     terminal: (
       name: string,
-    ) => (() => { kind: string; instance: ResourceInstance } | undefined) | undefined,
+    ) =>
+      | (() =>
+          | { kind: string; instance: ResourceInstance; manifest?: ResourceManifest }
+          | undefined)
+      | undefined,
   ): void {
     this.importedScopes.set(alias, { names: new Set(names), terminal });
   }
@@ -369,7 +378,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
         const kind = rawKind.startsWith("Self.")
           ? `${moduleName}.${rawKind.slice("Self.".length)}`
           : rawKind;
-        return { kind, instance: inst.instance };
+        // The manifest rides along because a DECLARATION-derived contract
+        // (`x-telo-schema-projection-from`) reads the target's own declaration,
+        // and a re-export forwards this getter verbatim — so carrying it here
+        // makes it reachable at any depth with no second table.
+        return { kind, instance: inst.instance, manifest: inst.resource };
       });
     }
     for (const k of kindEntries) {
@@ -407,6 +420,14 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     return scope.terminal(name)?.()?.instance;
   }
 
+  /** The manifest half of `resolveImportedInstance` — what a name was DECLARED
+   *  with, for a contract typed from a referenced declaration. */
+  override resolveImportedManifest(alias: string, name: string): ResourceManifest | undefined {
+    const scope = this.importedScopes.get(alias);
+    if (!scope || !scope.names.has(name)) return undefined;
+    return scope.terminal(name)?.()?.manifest;
+  }
+
   /** Like `resolveImportedInstance`, but returns the `{kind, name}` ref (canonical kind)
    *  for controllers that resolve step/handler invokes to refs rather than live instances
    *  (e.g. Run.Sequence via `ensureKindRef`). The alias is reattached by the caller. */

package/src/resource-context.ts

@@ -26,6 +26,7 @@ import {
   type ResourceHandle,
   type RuntimeSeam,
   type TypeRule,
+  type OpenZoneAttributes,
   type ZoneEntry,
 } from "@telorun/sdk";
 import { registerTeloKeywords } from "@telorun/analyzer";
@@ -426,6 +427,10 @@ export class ResourceContextImpl implements ResourceContext {
     return this.zoneContext().zonesFor(instance, ctx);
   }
 
+  zoneAttributes(ctx?: InvokeContext): readonly OpenZoneAttributes[] {
+    return this.zoneContext().zoneAttributes(ctx);
+  }
+
   /** The root context for runtime-driven inbound work — inherits nothing from
    *  whatever ambient happens to be live at the registration site. */
   rootContext(opts?: { cancellation?: CancellationSource }): InvokeContext {
@@ -514,6 +519,19 @@ export class ResourceContextImpl implements ResourceContext {
     return this.moduleContext.resolveImportedInstance(alias, name);
   }
 
+  /**
+   * The manifest a name was DECLARED with, resolved in the context that OWNS
+   * this resource — scope-local first, enclosing module as the fallback, an
+   * alias routing into that import's exports. The same order `resolveRef` and
+   * the CEL `resources` layering use, so a declaration lookup cannot disagree
+   * with them about what a name means.
+   *
+   * Used to resolve a DECLARATION-derived contract slot at bind time.
+   */
+  resolveDeclaredManifest(name: string, alias?: string): ResourceManifest | undefined {
+    return this.owningContext.resolveDeclaredManifest?.(name, alias);
+  }
+
   resolveRef<T>(
     value: unknown,
     guard: (candidate: unknown) => candidate is T,

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