@telorun/kernel 0.66.0 → 0.68.0

package/src/kernel.ts

@@ -1,6 +1,7 @@
 import {
   AnalysisRegistry,
   buildEvalPaths,
+  collectZoneModuleDocuments,
   flattenForAnalyzer,
   flattenLoadedModule,
   isModuleKind,
@@ -45,6 +46,7 @@ import { formatSpanCounter } from "./logging/span-id.js";
 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 { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
 import { stripCompiledValues } from "./schema-compiled-values.js";
@@ -70,6 +72,7 @@ import {
   collectDeclaredEnvKeys,
   precompileApplicationEnvSchemas,
   precompileDefinitionSchemas,
+  precompileTypeSchemas,
   resolveApplicationEnv,
 } from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
@@ -520,7 +523,10 @@ export class Kernel implements IKernel {
     const skipValidation = stamp?.signature === analysisSignature;
     const errors = this.analyzer.analyzeErrors(
       staticManifests,
-      { skipValidation },
+      // Imported libraries' full documents, for the zone stage's per-library
+      // export derivation: `flattenForAnalyzer` forwards only each library's
+      // export surface, never its internal dispatch chain.
+      { skipValidation, moduleDocuments: collectZoneModuleDocuments(analysisGraph) },
       this.registry,
     );
     if (errors.length > 0) {
@@ -566,6 +572,26 @@ export class Kernel implements IKernel {
       // same content-addressed `__validators/` cache the runtime reads. The
       // resolver lets it also bake each `extends` child's inheritance-resolved
       // schema — the form the runtime actually validates against.
+      //
+      // Named types first: a contract that is a `$ref` to one resolves through
+      // the schema registry, which at runtime is populated by the type
+      // resources' own init. Without them a `$ref` contract bakes nothing.
+      //
+      // Fed from the GRAPH, not from `staticManifests`: flatten forwards every
+      // module's definitions but only the ENTRY's resource instances, and a
+      // named type is a resource instance — so a library that declares its
+      // shapes once and `$ref`s them (`oauth-client`, `vector-store`) has no
+      // type doc in the flattened view at all.
+      const graphDocs = [...analysisGraph.modules.values()].flatMap((mod) =>
+        flattenLoadedModule(mod),
+      );
+      // Canonicalize `telo://Self/<type>` to the id the type registers under.
+      // `analyze()` did this to its own view; these projections are separate
+      // objects, and an un-canonicalized `$ref` resolves to nothing here while
+      // the runtime resolves it fine — a guaranteed miss on exactly the
+      // contracts that reference a named shape.
+      this.registry.resolveSchemaTypeRefs([...graphDocs, ...staticManifests]);
+      await precompileTypeSchemas(graphDocs, this.sharedSchemaValidator);
       precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator, (def) =>
         this.registry.resolverForDefinition(def),
       );
@@ -1286,6 +1312,17 @@ export class Kernel implements IKernel {
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;
 
+    // Mint the instance's identity here, at the single instance-production site,
+    // so an instance is never observable without a handle — the same argument
+    // that put contract binding here. First mint wins: a `base:` child IS the
+    // parent instance returned verbatim and must not be re-identified.
+    const handle = mintResourceHandle(
+      instance,
+      resolvedKind,
+      (processedResource.metadata?.name as string | undefined) ?? "<unnamed>",
+    );
+    (ctx as ResourceContextImpl).bindResourceIdentity(handle, resolvedKind, processedResource);
+
     // Bind the resolved invocation contract to the instance, here at the kernel's
     // single instance-production site — so every consumer holds an already
     // enforcing instance, including the majority that read a Phase-5-injected ref

package/src/manifest-schemas.ts

@@ -96,6 +96,12 @@ const KNOWN_CAPABILITIES = [
   // path, and dispatch emits trace events, so routing logs through it would
   // generate telemetry from inside the telemetry path. See kernel/specs/logging.md §10.
   "Telo.Sink",
+  // `Telo.Executable` is deliberately declarable NOWHERE: it is the slot-
+  // constraint parent of Invocable and Runnable ("control can be transferred to
+  // this"), naming no lifecycle role. Listing it here keeps the open third-party
+  // fallback branch below from accepting it — and since no branch above admits
+  // it either, `capability: Telo.Executable` fails validation outright.
+  "Telo.Executable",
 ] as const;
 
 /** Rule 8: `throws:` is only meaningful on Telo.Invocable or Telo.Runnable.

package/src/module-context.ts

@@ -1,4 +1,4 @@
-import { executeInvokeStep, getRefIdentity, RuntimeError } from "@telorun/sdk";
+import { deriveContext, executeInvokeStep, getRefIdentity, RuntimeError } from "@telorun/sdk";
 import type { ScopeConfig } from "./logging/scope-config.js";
 import type {
   BootTarget,
@@ -585,12 +585,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       );
     const targetCtx: InvokeContext | undefined =
       tracing && ctx
-        ? {
-            cancellation: ctx.cancellation,
+        ? deriveContext(ctx, {
             invocationId: appSpanId,
             parentInvocationId: undefined,
             traceId: appTraceId,
-          }
+          })
         : ctx;
 
     const steps: Record<string, unknown> = {};

package/src/resource-context.ts

@@ -1,15 +1,20 @@
 import {
+  InvokeError,
   NoopValidator,
   ResourceContext,
   ResourceInstance,
   ResourceManifest,
   RuntimeError,
   RuntimeResource,
+  UNCANCELLABLE_CONTEXT,
   createCancellationSource,
+  deriveContext,
+  getRefIdentity,
   resolveRefInstance,
   type CancellationSource,
   type ControllerPolicy,
   type EvaluationContext as IEvaluationContext,
+  type InvokeByNameOptions,
   type InvokeContext,
   type LoadOptions,
   type ModuleContext,
@@ -17,10 +22,14 @@ import {
   type OpenSpan,
   type OpenSpanOptions,
   type ParsedArgs,
+  type ResourceDefinition,
+  type ResourceHandle,
   type RuntimeSeam,
   type TypeRule,
+  type ZoneEntry,
 } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
+import { ZoneContext } from "./zone-context.js";
 import * as path from "path";
 import { pathToFileURL } from "url";
 import type { ModuleArtifact } from "./bundle/module-artifact.js";
@@ -34,6 +43,7 @@ interface KernelModuleContext {
   getLoggingConfig?(): ScopeConfig | undefined;
 }
 import { stripCompiledValues } from "./schema-compiled-values.js";
+import { resolveTypeFieldSchema } from "./type-field-schema.js";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 import { Kernel } from "./kernel.js";
@@ -170,7 +180,12 @@ export class ResourceContextImpl implements ResourceContext {
     if (!schema) {
       return new NoopValidator();
     }
-    return this.validator.compile(schema);
+    // Never persisted: the schema is author data in a RESOURCE field, which the
+    // build-time warm does not walk, so a disk entry could only ever miss and
+    // be rewritten on every boot. Compiling through the kernel's validator is
+    // still what keeps one engine in the process — its formats, its `x-telo-*`
+    // keywords, its non-strict mode.
+    return this.validator.compile(schema, { persist: false });
   }
 
   registerSchema(name: string, schema: object): void {
@@ -207,54 +222,13 @@ export class ResourceContextImpl implements ResourceContext {
    *  anyway, for the decisions a validator cannot answer: which properties carry
    *  `x-telo-stream` and must be exempt from the walk, and which paths a
    *  `default:` can be written to. Returns undefined when the reference resolves
-   *  to nothing. */
-  resolveTypeSchema(typeRef: unknown): Record<string, any> | undefined {
-    return this.followTypeAlias(this.readTypeSchema(typeRef), new Set());
-  }
-
-  private readTypeSchema(typeRef: unknown): Record<string, any> | undefined {
-    if (!typeRef) return undefined;
-    if (typeof typeRef === "string") return this.validator.getSchema(typeRef) as any;
-    if (typeof typeRef !== "object") return undefined;
-    const ref = typeRef as Record<string, any>;
-    if (ref.schema && typeof ref.schema === "object") return ref.schema;
-    if (typeof ref.name === "string") return this.validator.getSchema(ref.name) as any;
-    if (ref.type || ref.properties || ref.$ref) return ref;
-    return undefined;
-  }
-
-  /**
-   * Follow a schema that is nothing but a `$ref` to a registered type, so the
-   * schema-level questions (which properties are streams, which paths carry a
-   * default) are asked of the real shape rather than of an alias.
-   *
-   * Only the whole-document alias form is followed, and only to READ it — the
-   * schema handed to AJV keeps its `$ref`s intact, because AJV resolves them
-   * itself against the registered ids and each type stays its own document with
-   * its own `$defs`. Inlining instead would move a `$ref: "#/$defs/X"` out of the
-   * document that defines `$defs.X`.
+   *  to nothing.
    *
-   * `seen` guards a cycle two mutually-referencing types would otherwise spin on.
-   * A `$ref` alongside other keywords is left alone: that is a composition, not
-   * an alias.
-   */
-  private followTypeAlias(
-    schema: Record<string, any> | undefined,
-    seen: Set<string>,
-  ): Record<string, any> | undefined {
-    let current = schema;
-    while (
-      current &&
-      typeof current.$ref === "string" &&
-      Object.keys(current).length === 1 &&
-      !seen.has(current.$ref)
-    ) {
-      seen.add(current.$ref);
-      const target = this.validator.getSchema(current.$ref) as Record<string, any> | undefined;
-      if (!target) return current;
-      current = target;
-    }
-    return current;
+   *  Shared with the build-time validator warm through
+   *  {@link resolveTypeFieldSchema} — the warm must land on the same schema
+   *  object the runtime compiles, or its baked entry is one nothing asks for. */
+  resolveTypeSchema(typeRef: unknown): Record<string, any> | undefined {
+    return resolveTypeFieldSchema(typeRef, (name) => this.validator.getSchema(name));
   }
 
   /** Compile `schema` but compose the CEL `rules:` registered under `name`.
@@ -350,6 +324,88 @@ export class ResourceContextImpl implements ResourceContext {
     return createCancellationSource();
   }
 
+  // ── Execution zones (kernel/specs/execution-zones.md) ─────────────────────
+  //
+  // Identity is held here (it is the resource's, not the zone subsystem's);
+  // everything else delegates to `ZoneContext`, which owns the annotation
+  // resolution, correlation walk and stack matching — and memoizes them, since
+  // this sits on the dispatch path.
+
+  #self: ResourceHandle | undefined;
+  #zones: ZoneContext | undefined;
+
+  /** Kernel-internal: stamped at `create()`, the moment the instance exists. */
+  bindResourceIdentity(
+    handle: ResourceHandle,
+    resolvedKind: string,
+    manifest: Record<string, unknown>,
+  ): void {
+    this.#self = handle;
+    this.#zones = new ZoneContext({
+      resourceName: (this.metadata?.name as string) ?? "<unnamed>",
+      resolvedKind,
+      self: handle,
+      // The SAME object Phase-5 injection later mutates, so a correlation
+      // pointer read at invoke time sees live instances in ref slots.
+      manifest,
+      resolveDefinition: (kind) => this.kernel.getAnalysisRegistry().resolveDefinition(kind),
+      resolveDefinitionIn: (kind, module) =>
+        this.kernel.getAnalysisRegistry().resolveDefinitionIn(kind, module),
+      resolveLocalInstance: (name) => this.resolveLocalInstance(name),
+      resolveLocalManifest: (name) =>
+        this.contextForName(name).resourceInstances.get(name)?.resource as
+          | Record<string, unknown>
+          | undefined,
+    });
+  }
+
+  get self(): ResourceHandle {
+    if (!this.#self) {
+      throw new RuntimeError(
+        "ERR_RESOURCE_IDENTITY_UNBOUND",
+        `[${this.metadata.name}] ctx.self is unavailable inside create() — the handle is minted when create() returns`,
+      );
+    }
+    return this.#self;
+  }
+
+  /** The zone subsystem, available once `create()` has returned. */
+  private zoneContext(): ZoneContext {
+    if (!this.#zones) {
+      throw new RuntimeError(
+        "ERR_RESOURCE_IDENTITY_UNBOUND",
+        `[${this.metadata.name}] zones are unavailable inside create() — the handle is minted when create() returns`,
+      );
+    }
+    return this.#zones;
+  }
+
+  withZone<T>(
+    slot: string,
+    fn: (ctx: InvokeContext, entry: ZoneEntry) => Promise<T>,
+    base?: InvokeContext,
+  ): Promise<T> {
+    return this.zoneContext().withZone(slot, fn, base);
+  }
+
+  requireZone(field: string, ctx?: InvokeContext): ZoneEntry {
+    return this.zoneContext().requireZone(field, ctx);
+  }
+
+  findZone(field: string, ctx?: InvokeContext): ZoneEntry | undefined {
+    return this.zoneContext().findZone(field, ctx);
+  }
+
+  zonesFor(instance: ResourceInstance, ctx?: InvokeContext): readonly ZoneEntry[] {
+    return this.zoneContext().zonesFor(instance, 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 {
+    return opts?.cancellation?.context ?? UNCANCELLABLE_CONTEXT;
+  }
+
   /** In-flight fire-and-forget tasks this resource spawned. Owned here, not by
    *  the kernel: the resource drains them in its own teardown (see
    *  `drainDetached`), so background work is bounded by the resource's lifetime. */
@@ -401,8 +457,13 @@ export class ResourceContextImpl implements ResourceContext {
     return this.owningContext.openSpan(base, opts);
   }
 
-  invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any> {
-    return this.contextForName(name).invoke(kind, name, inputs);
+  invoke<TInputs>(
+    kind: string,
+    name: string,
+    inputs: TInputs,
+    options?: InvokeByNameOptions,
+  ): Promise<any> {
+    return this.contextForName(name).invoke(kind, name, inputs, options?.ctx);
   }
 
   invokeResolved<TInputs>(

package/src/resource-handle.ts

@@ -0,0 +1,35 @@
+import type { ResourceHandle, ResourceInstanceId } from "@telorun/sdk";
+
+/**
+ * Instance → handle, minted at `create()` — the kernel's single
+ * instance-production site, where the invocation contract already binds — so an
+ * instance is never observable without one. The reverse direction deliberately
+ * does not exist: nothing turns a handle back into someone else's live
+ * instance, which is what keeps the ambient zone stack from leaking instances
+ * across module boundaries.
+ */
+const handles = new WeakMap<object, ResourceHandle>();
+
+let counter = 0;
+
+/**
+ * Mint (or return) the handle for a live instance. Idempotent, first mint wins
+ * — a `base:` child IS its parent's instance returned verbatim, so the nested
+ * parent create stamps first and the child create must not re-identify it; one
+ * live instance, one id, exactly like `stampRefIdentity`.
+ */
+export function mintResourceHandle(instance: object, kind: string, name: string): ResourceHandle {
+  const existing = handles.get(instance);
+  if (existing) return existing;
+  const handle: ResourceHandle = Object.freeze({
+    id: `ri-${++counter}` as ResourceInstanceId,
+    ref: Object.freeze({ kind, name }),
+  });
+  handles.set(instance, handle);
+  return handle;
+}
+
+/** The handle minted for a live instance, if any. */
+export function handleOfInstance(instance: object): ResourceHandle | undefined {
+  return handles.get(instance);
+}

package/src/runtime-seam.ts

@@ -1,9 +1,11 @@
 import {
   Loader,
   StaticAnalyzer,
+  collectZoneModuleDocuments,
   flattenForAnalyzer,
   type AnalysisDiagnostic,
   type ManifestSource,
+  type ZoneModuleDocuments,
 } from "@telorun/analyzer";
 import {
   Stream,
@@ -211,6 +213,7 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     // `analyze()`'s — carried out of the try so the checks below can see them.
     let parseDiagnostics: AnalysisDiagnostic[] = [];
     let versionDiagnostics: AnalysisDiagnostic[] = [];
+    let moduleDocuments: ZoneModuleDocuments[] = [];
     try {
       const graph = await loader.loadGraph(source, {
         desugarImports: options?.desugarImports ?? true,
@@ -219,6 +222,9 @@ export class KernelRuntimeSeam implements RuntimeSeam {
       parseDiagnostics = graph.parseDiagnostics;
       versionDiagnostics = graph.versionDiagnostics;
       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);
     } 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
@@ -243,7 +249,9 @@ export class KernelRuntimeSeam implements RuntimeSeam {
 
     // `analyze()` never sees version skew, so without merging these a major
     // mismatch — which `load()` refuses to boot on — would check clean.
-    const diagnostics = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests);
+    const diagnostics = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests, {
+      moduleDocuments,
+    });
     return {
       diagnostics: [...versionDiagnostics, ...diagnostics].map(toCheckDiagnostic),
     };

package/src/schema-compiled-values.ts

@@ -61,6 +61,35 @@ function collectSchemaProperties(
   return props;
 }
 
+/** True when a ref slot is holding CONFIG rather than a reference.
+ *
+ *  A slot annotated `x-telo-ref` is normally handed back whole, but the
+ *  annotation can sit on a node that is a reference AND a config carrier at
+ *  once: `targets:` puts it on the array ITEM so a bare `!ref Foo` is accepted,
+ *  while the same item may be a step object (`{ref, when}` /
+ *  `{invoke, inputs, when}`) whose `when` is a CEL guard that must be stripped
+ *  like any other. Told apart by what the value IS, three ways:
+ *
+ *  - a reference carries a `kind` — `resolveRefSentinels` rewrites a `!ref` to
+ *    `{kind, name, alias?}`, and the only other object a ref slot admits is an
+ *    inline definition (`{kind, …config}`);
+ *  - a live instance is either not a plain object, or exposes a method (a
+ *    controller's `create()` may return an object literal — `Assert.Schema`
+ *    does). Copying one is what the walk exists to avoid, and its graph is
+ *    routinely cyclic;
+ *  - what is left came from YAML, where a function cannot appear. */
+function isConfigAtRefSlot(value: unknown): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  const obj = value as Record<string, unknown>;
+  if ("kind" in obj) return false;
+  for (const member of Object.values(obj)) {
+    if (typeof member === "function") return false;
+  }
+  return true;
+}
+
 /** Replaces CompiledValue wrappers with schema-appropriate placeholders for schema validation.
  *  Template strings were compiled from YAML at load time; this restores a shape
  *  that AJV can validate without evaluating expressions. When no schema is
@@ -88,10 +117,13 @@ export function stripCompiledValues(
     const resolved = resolveSchemaRef(nodeSchema, root);
 
     if (isCompiledValue(value)) return placeholderForSchema(resolved);
-    // A slot the schema declares as a reference is never config: it holds a
-    // `{kind, name}` ref or the live instance Phase 5 replaced it with, and the
-    // schema declares no shape to validate against either way.
-    if (resolved["x-telo-ref"] !== undefined) return value;
+    // A slot the schema declares as a reference is never config when it HOLDS a
+    // reference: a `{kind, name}` ref or the live instance Phase 5 replaced it
+    // with, and the schema declares no shape to validate against either way. A
+    // ref slot carrying config beside the ref keeps walking — bailing there left
+    // a boot target's `when: !cel` a CompiledValue for AJV to reject as
+    // "must be string", which is the whole gated-target form.
+    if (resolved["x-telo-ref"] !== undefined && !isConfigAtRefSlot(value)) return value;
 
     if (Array.isArray(value)) {
       const itemSchema = resolveSchemaRef((resolved.items ?? {}) as Record<string, unknown>, root);

package/src/schema-validator.ts

@@ -146,6 +146,64 @@ function collapseSentinelsToSource(value: unknown): unknown {
   return value;
 }
 
+/** Schema keywords whose VALUE is a map keyed by author-chosen names rather
+ *  than by keyword. A name may legitimately be `x-telo-…`, so the strip below
+ *  must not treat a key in one of these maps as an annotation. */
+const NAME_KEYED_SCHEMA_KEYWORDS = new Set([
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "dependentRequired",
+  "$defs",
+  "definitions",
+]);
+
+/** Schema keywords whose value is DATA, not a subschema. The strip must not
+ *  descend into them at all: an `x-telo-…` key inside a `const` / `default` /
+ *  `enum` member is part of the value being matched or filled, so removing it
+ *  would change what the validator accepts and what it writes — and would make
+ *  two schemas that differ only there hash alike. */
+const DATA_VALUE_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
+
+/** Deep-clone `schema` without its `x-telo-*` annotations — applied, like
+ *  {@link collapseSentinelsToSource}, before both AJV compilation and cache
+ *  hashing.
+ *
+ *  Every `x-telo-*` keyword is analyzer/editor metadata: AJV runs `strict:
+ *  false` and registers the known ones as no-op keywords, so none of them emits
+ *  a single line of validation code. Leaving them in the hashed form makes the
+ *  cache key sensitive to differences that cannot change what the validator
+ *  does — and one such difference is real and systematic. The analyzer rewrites
+ *  `x-telo-ref.kind` to its canonical `<module>.<Kind>` in the declaring scope
+ *  (`resolveSchemaRefKinds`), and `telo install`'s warm pass bakes THAT view;
+ *  the kernel's controller registry never runs the rewrite, so at runtime the
+ *  same kind's schema still reads `Self.Connection`. Two keys, one validator:
+ *  every kind whose schema declares an alias-qualified ref missed the baked
+ *  cache on every boot and tried to rewrite it — the EACCES noise on a
+ *  read-only image.
+ *
+ *  Stripping is what makes the key describe the compiled validator and nothing
+ *  else, so the two views converge without either side having to agree on an
+ *  annotation's spelling. `normalizeRefSlots` runs FIRST and is unaffected: it
+ *  reads `x-telo-ref` to drop a legacy scalar `type` at a ref slot, which does
+ *  change validation, and it has already done so by the time this runs. */
+function stripTeloAnnotations(value: unknown, nameKeyed = false): unknown {
+  // An array's items are schema nodes (`allOf`, tuple `items`), never names.
+  if (Array.isArray(value)) return value.map((item) => stripTeloAnnotations(item));
+  if (!value || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (!nameKeyed && k.startsWith("x-telo-")) continue;
+    // A data-bearing keyword's value is carried over verbatim; a name-keyed
+    // map's VALUES are schema nodes again, so only its keys are exempt.
+    out[k] =
+      !nameKeyed && DATA_VALUE_KEYWORDS.has(k)
+        ? v
+        : stripTeloAnnotations(v, !nameKeyed && NAME_KEYED_SCHEMA_KEYWORDS.has(k));
+  }
+  return out;
+}
+
 export class SchemaValidator {
   private ajv: InstanceType<typeof Ajv>;
   private typeRules = new Map<string, TypeRule[]>();
@@ -162,6 +220,13 @@ export class SchemaValidator {
    *  process — `compiledValidators` is keyed by object identity and would
    *  miss those cases. */
   private hashCache = new Map<string, DataValidator>();
+  /** Hashes whose compile went through the disk layer. A `persist: false`
+   *  compile populates `hashCache` too — a repeat within the process should
+   *  still collapse — but must not be mistaken for a baked entry: returning it
+   *  to a persisting caller would suppress that caller's write permanently, so
+   *  content shared with a warmable schema would never reach the cache. Such a
+   *  caller falls through and compiles again, this time with the disk layer. */
+  private persistedHashes = new Set<string>();
   /** Where cache-failure diagnostics go. Injected rather than reached for
    *  globally: this class is constructed outside the kernel's stdio scope, and
    *  §13.1 forbids the kernel writing to `process.stderr` directly. Defaults to
@@ -239,7 +304,18 @@ export class SchemaValidator {
     this.cacheWritable = opts?.write ?? true;
   }
 
-  compile(schema: any): DataValidator {
+  /** Compile `schema` to a validator, reusing the in-memory and on-disk caches.
+   *
+   *  `persist: false` keeps the compile in memory only — no disk read, no disk
+   *  write. It is for a schema the build-time warm cannot see: an author-written
+   *  JSON Schema sitting in a RESOURCE field (`ctx.createSchemaValidator`),
+   *  rather than a kind's config schema or an invocation contract. Those are
+   *  baked by `precompileDefinitionSchemas`; a resource-field schema never was,
+   *  so persisting it only ever produced a miss-then-write on every boot — the
+   *  EACCES noise on a read-only image. Declining to own what it cannot warm is
+   *  the cache being honest, not a capability given up: the in-memory layers
+   *  still collapse a repeat compile within the process. */
+  compile(schema: any, options?: { persist?: boolean }): DataValidator {
     if (schema && typeof schema === "object") {
       const cached = this.compiledValidators.get(schema as object);
       if (cached) return cached;
@@ -284,7 +360,7 @@ export class SchemaValidator {
     // precompiled (runtime) views of one schema land on the same cache key. The
     // hashed and the compiled schema are this same canonical form. See
     // `collapseSentinelsToSource`.
-    const sanitized = collapseSentinelsToSource(injected);
+    const sanitized = collapseSentinelsToSource(stripTeloAnnotations(injected));
 
     const hash = createHash("sha256")
       .update(
@@ -295,15 +371,17 @@ export class SchemaValidator {
       )
       .digest("hex")
       .slice(0, 32);
+    const persist = options?.persist ?? true;
     const cachedByHash = this.hashCache.get(hash);
-    if (cachedByHash) {
+    if (cachedByHash && (!persist || this.persistedHashes.has(hash))) {
       if (schema && typeof schema === "object") {
         this.compiledValidators.set(schema as object, cachedByHash);
       }
       return cachedByHash;
     }
 
-    const validate = this.compileAjvOrLoadCached(sanitized, hash);
+    const validate = this.compileAjvOrLoadCached(sanitized, hash, persist);
+    if (persist) this.persistedHashes.add(hash);
 
     const validator = {
       validate: (data: any) => {
@@ -342,8 +420,12 @@ export class SchemaValidator {
   private compileAjvOrLoadCached(
     schema: any,
     hash: string,
+    persist: boolean,
   ): ValidateFunction {
-    const cacheDir = this.cacheDir;
+    // `persist: false` drops the whole disk layer — the read too, not just the
+    // write. Nothing bakes these entries, so a lookup is an ENOENT probe whose
+    // only possible hit is one this process wrote on an earlier run.
+    const cacheDir = persist ? this.cacheDir : undefined;
     if (cacheDir) {
       const cachePath = path.join(cacheDir, `${hash}.cjs`);
       try {