@telorun/kernel 0.59.0 → 0.61.0

package/src/controller-loaders/bundle-loader.ts

@@ -1,3 +1,4 @@
+import { describeSelector, selectorFromQualifiers, selectorMatches } from "@telorun/analyzer";
 import { ControllerInstance, RuntimeError } from "@telorun/sdk";
 import { existsSync, readFileSync } from "fs";
 import * as fs from "fs/promises";
@@ -5,10 +6,18 @@ import { createRequire } from "module";
 import { PackageURL } from "packageurl-js";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
+import { hostPlatformTarget, type ModuleArtifact } from "../bundle/module-artifact.js";
 import type { ControllerResolveSource } from "../controller-loader.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.js";
 
+/** A base URI whose files are already on disk: a `file://` URL or a bare
+ *  absolute path. Everything else (`oci://`, `http(s)://`, `memory://`) names a
+ *  module whose payload only exists inside an artifact. */
+function isLocalBase(baseUri: string): boolean {
+  return baseUri.startsWith("file://") || path.isAbsolute(baseUri);
+}
+
 async function pathExists(filePath: string): Promise<boolean> {
   try {
     await fs.access(filePath);
@@ -140,20 +149,23 @@ export class BundleControllerLoader {
   async load(
     purl: string,
     baseUri: string,
+    artifact?: ModuleArtifact,
   ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
-    const { source, importInstance } = await this.resolve(purl, baseUri);
+    const { source, importInstance } = await this.resolve(purl, baseUri, artifact);
     return { instance: await importInstance(), source };
   }
 
   /**
-   * Resolve without importing: parse + validate the PURL, confirm the bundle
-   * file exists and its format is hostable, and ensure the realm symlinks — all
-   * cheap, fail-fast checks — but defer the bundle `import()` (the eval cost)
-   * into the returned `importInstance` thunk. Used by lazy controller loading.
+   * Resolve without importing: parse + validate the PURL, reject a candidate this
+   * host cannot run, materialize the layer that carries it, confirm the file
+   * exists, and ensure the realm symlinks — all fail-fast checks — but defer the
+   * bundle `import()` (the eval cost) into the returned `importInstance` thunk.
+   * Used by lazy controller loading.
    */
   async resolve(
     purl: string,
     baseUri: string,
+    artifact?: ModuleArtifact,
   ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     let parsed: PackageURL;
     try {
@@ -190,16 +202,50 @@ export class BundleControllerLoader {
       );
     }
 
-    // Bundles are local files next to the manifest. A remote (http) baseUri
-    // can't host one, so defer to the next candidate.
-    if (baseUri.startsWith("http://") || baseUri.startsWith("https://")) {
+    // Platform gate, BEFORE any materialization. A candidate list names one
+    // binary per platform, so checking the host first is what keeps a fallthrough
+    // from downloading every platform's layer on the way to the right one.
+    const selector = selectorFromQualifiers(format, parsed.qualifiers, `controller "${purl}"`);
+    const host = hostPlatformTarget();
+    if (!selectorMatches(selector, host)) {
       throw new ControllerEnvMissingError(
-        `pkg:telo controller "${purl}" requires a local manifest; baseUri is remote (${baseUri})`,
+        `pkg:telo controller "${purl}" targets ${describeSelector(selector)}, which does not ` +
+          `match this host (${host.os ?? "unknown os"}/${host.arch ?? "unknown arch"}` +
+          `${host.libc ? `/${host.libc}` : ""})`,
       );
     }
 
-    const basePath = baseUri.startsWith("file://") ? fileURLToPath(baseUri) : baseUri;
-    const absFile = path.resolve(path.dirname(basePath), relPath);
+    // A published module's payload lives in its artifact, so materialize the one
+    // layer carrying this candidate and resolve `path=` inside it. Nothing is
+    // fetched here: the artifact handle owns the pinned ref and the verified
+    // layer index, so an `oci://` module ref never reaches this loader as a path.
+    let bundleDir: string;
+    if (artifact) {
+      // By its own selector, not by re-matching the host: this candidate IS one
+      // selector, and it is exactly the key of the layer that carries it.
+      const layer = await artifact.materializeController(selector);
+      if (!layer) {
+        throw new ControllerEnvMissingError(
+          `pkg:telo controller "${purl}": the module artifact ships no layer for ` +
+            `${describeSelector(selector)} (has: ${artifact.describeLayers()})`,
+        );
+      }
+      bundleDir = layer.dir;
+    } else {
+      // No artifact: a module already on disk (local development, or a manifest
+      // served from the on-disk cache). Its files sit next to the manifest.
+      if (!isLocalBase(baseUri)) {
+        throw new ControllerEnvMissingError(
+          `pkg:telo controller "${purl}" cannot be located: the declaring module resolved from ` +
+            `"${baseUri}", which is neither a local path nor an artifact with a layer index. ` +
+            `A bundled controller ships in its module's artifact — republish the module, or ` +
+            `import it from a local path during development.`,
+        );
+      }
+      bundleDir = path.dirname(baseUri.startsWith("file://") ? fileURLToPath(baseUri) : baseUri);
+    }
+
+    const absFile = path.resolve(bundleDir, relPath);
     if (!(await pathExists(absFile))) {
       throw new ControllerEnvMissingError(
         `pkg:telo controller bundle not found at "${absFile}" (from "${purl}")`,

package/src/controller-loaders/npm-loader.ts

@@ -10,6 +10,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 import { promisify } from "util";
 import { hostEnv } from "../host-env.js";
 import { tryBuildControllerBundle } from "./bundle-builder.js";
+import { withDirectoryLock } from "../directory-lock.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.js";
 
@@ -43,39 +44,6 @@ const PEER_INSTALL_FLAGS: ReadonlyArray<string> =
       ? ["--no-strict-peer-dependencies"]
       : [];
 
-/**
- * A held lock is refreshed (its mtime bumped) every {@link LOCK_HEARTBEAT_MS}
- * by the holder. Staleness is judged purely by mtime age — a lock older than
- * this means the holder stopped heartbeating (crashed, was killed, or its
- * container vanished), so it is safe to reclaim. This deliberately does NOT
- * probe the recorded PID for liveness: PID identity is meaningless across
- * container restarts and PID namespaces (deterministic PID reuse makes an
- * unrelated process look like the dead holder on the same hostname), which is
- * exactly what deadlocked container boots. The `{pid, host}` in the lock body
- * is diagnostics for humans, never a reclaim signal. Must be comfortably
- * larger than the heartbeat interval so a briefly-descheduled holder (GC
- * pause, busy event loop) is not reclaimed out from under itself.
- */
-const LOCK_STALE_MS = 30_000;
-
-/** How often the holder refreshes the lock mtime while `fn` runs. Well under
- *  {@link LOCK_STALE_MS} so several heartbeats are missed before a live holder
- *  is ever judged stale. */
-const LOCK_HEARTBEAT_MS = 5_000;
-
-/**
- * Total wall-clock cap for waiting on the install lock — enough for a slow
- * first install on a peer process to finish, short enough that a genuinely
- * deadlocked CI job fails loudly rather than hanging for hours. The retry
- * interval trades wakeup latency vs. wasted polls; 500ms is well below the
- * lock holder's typical hold time.
- */
-const LOCK_WAIT_MAX_MS = 5 * 60_000;
-const LOCK_RETRY_MS = 500;
-
-/** After this long waiting on a lock, emit one stderr line so a slow wait is
- *  visible instead of looking like a silent hang. */
-const LOCK_WAIT_NOTICE_MS = 2_000;
 
 /**
  * Tells the dispatcher (and any UI consumer downstream) which branch the
@@ -325,7 +293,7 @@ export class NpmControllerLoader {
       return installRoot;
     }
 
-    await withInstallLock(installRoot, async () => {
+    await withDirectoryLock(installRoot, "controller install", async () => {
       // Re-check inside the lock: a peer may have completed the install
       // between the fast-path miss and our acquisition.
       const existingHash = await readJsonField(stateFile, "rootHash");
@@ -447,7 +415,7 @@ export class NpmControllerLoader {
     }
 
     const work = (async () => {
-      await withInstallLock(installRoot, async () => {
+      await withDirectoryLock(installRoot, "controller install", async () => {
         // Re-check inside the lock: a peer process may have installed the
         // spec between the fast-path miss and our acquisition.
         if (kind === "registry") {
@@ -557,176 +525,6 @@ async function resolveKernelPackageRoot(name: string): Promise<string | null> {
   }
 }
 
-/**
- * Serialize same-process callers for one install root, in memory, ahead of the
- * filesystem lock.
- *
- * Package installs dedupe per alias, so N distinct controllers are N distinct
- * `withInstallLock` calls against the SAME root. Without this queue they all
- * contend through the filesystem: one wins and the rest poll `fs.open` every
- * {@link LOCK_RETRY_MS} for the whole install, each crossing
- * {@link LOCK_WAIT_NOTICE_MS} and printing the wait notice — a notice whose
- * whole point is "another Telo *process* holds this", which is misleading when
- * the holder is us. (`telo install` fanning 52 controllers out through one
- * `Promise.allSettled` printed 51 of them.)
- *
- * Queuing here means exactly one caller per process reaches the fs lock, so the
- * notice regains its cross-process meaning and the losers do no I/O at all. The
- * fs lock is untouched and still provides the cross-process guarantee.
- */
-const localInstallQueues = new Map<string, Promise<unknown>>();
-
-function withLocalInstallQueue<T>(installRoot: string, fn: () => Promise<T>): Promise<T> {
-  const prev = localInstallQueues.get(installRoot) ?? Promise.resolve();
-  // Run on both settle paths: one failed install must not wedge the queue.
-  const run = prev.then(fn, fn);
-  // The stored tail never rejects — a failure neither poisons followers nor
-  // surfaces as an unhandled rejection on the chain copy.
-  const tail = run.then(
-    () => {},
-    () => {},
-  );
-  localInstallQueues.set(installRoot, tail);
-  // Drop the entry once nothing further is queued, so a long-lived process that
-  // touches many entry dirs doesn't retain a promise per root forever.
-  void tail.then(() => {
-    if (localInstallQueues.get(installRoot) === tail) localInstallQueues.delete(installRoot);
-  });
-  return run;
-}
-
-/**
- * Acquire the install lock for `installRoot` and run `fn` under it: first the
- * in-process queue above, then the cross-process filesystem lock.
- */
-async function withInstallLock<T>(
-  installRoot: string,
-  fn: () => Promise<T>,
-  log: Logger = NOOP_LOGGER,
-): Promise<T> {
-  return withLocalInstallQueue(installRoot, () => withFileInstallLock(installRoot, fn, log));
-}
-
-/**
- * Acquire a process-portable lock on `<root>/.lock` and execute fn while
- * holding it. `fs.open(path, 'wx')` is atomic on POSIX and Windows, so
- * concurrent processes serialize naturally.
- *
- * Liveness is a heartbeat: the holder bumps the lock's mtime every
- * {@link LOCK_HEARTBEAT_MS} while `fn` runs, and a waiter reclaims a lock whose
- * mtime is older than {@link LOCK_STALE_MS} (holder crashed/killed/vanished).
- * mtime age is the *only* reclaim signal — the recorded `{pid, host}` is
- * diagnostics, never probed for liveness, because PID identity is unreliable
- * across container restarts and PID namespaces (the failure that deadlocked
- * container boots). Reclaim is via atomic rename to a unique tombstone so two
- * waiters that both see the lock stale can't both win.
- *
- * The lock guards the install-root manifest write, the package-manager
- * invocation, and any state-file writes. It does NOT serialize *reads* of
- * already-installed controllers — those run lock-free against a stable tree.
- */
-async function withFileInstallLock<T>(
-  installRoot: string,
-  fn: () => Promise<T>,
-  log: Logger = NOOP_LOGGER,
-): Promise<T> {
-  const lockPath = path.join(installRoot, ".lock");
-
-  await fs.mkdir(installRoot, { recursive: true });
-
-  const lockBody = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now() });
-  let handle: import("fs/promises").FileHandle | null = null;
-  const waitedSince = Date.now();
-  let noticed = false;
-  while (true) {
-    try {
-      handle = await fs.open(lockPath, "wx");
-      await handle.writeFile(lockBody);
-      break;
-    } catch (err: any) {
-      if (err?.code !== "EEXIST") throw err;
-      // Lock exists. Reclaim it only if its heartbeat has gone silent.
-      if (await reclaimIfStale(lockPath)) continue;
-      const waited = Date.now() - waitedSince;
-      if (waited > LOCK_WAIT_MAX_MS) {
-        throw new Error(
-          `[telo] timed out waiting for install lock at ${lockPath} ` +
-            `(held >${LOCK_WAIT_MAX_MS / 60_000} min with a live heartbeat). ` +
-            `Inspect the lock file or remove it manually if no other Telo process is running.`,
-        );
-      }
-      if (!noticed && waited > LOCK_WAIT_NOTICE_MS) {
-        noticed = true;
-        log.info("waiting for controller install lock", { "telo.install.lock_path": lockPath });
-      }
-      await sleep(LOCK_RETRY_MS);
-    }
-  }
-
-  // Keep the lock fresh while `fn` runs so a slow-but-live install is never
-  // reclaimed. `unref` so the heartbeat can't by itself keep the process alive.
-  const heartbeat = setInterval(() => {
-    const now = new Date();
-    fs.utimes(lockPath, now, now).catch(() => {});
-  }, LOCK_HEARTBEAT_MS);
-  heartbeat.unref?.();
-
-  try {
-    return await fn();
-  } finally {
-    clearInterval(heartbeat);
-    // The fd close races nothing important: if it fails, the FD is reaped on
-    // process exit. The unlink is the dangerous one — a non-ENOENT failure
-    // (permissions, read-only mount) means every subsequent kernel waits
-    // LOCK_STALE_MS before reclaiming. Surface it so the cause is visible
-    // rather than hiding behind a silent hang.
-    await handle!.close().catch(() => {});
-    try {
-      await fs.rm(lockPath, { force: true });
-    } catch (err: any) {
-      if (err?.code !== "ENOENT") {
-        log.warn(
-          "failed to release install lock",
-          { "telo.install.lock_path": lockPath },
-          { error: err },
-        );
-      }
-    }
-  }
-}
-
-/**
- * If the lock at `lockPath` is stale (mtime older than {@link LOCK_STALE_MS}, so
- * its holder stopped heartbeating), atomically claim and remove it and return
- * true; otherwise return false. The claim is a `rename` to a unique tombstone:
- * `rename` is atomic and fails for all but one racer, so two processes that
- * both observe the same stale lock cannot both reclaim it — the loser's rename
- * throws ENOENT (the file is already gone) and it simply retries the open.
- */
-async function reclaimIfStale(lockPath: string): Promise<boolean> {
-  let stat: import("fs").Stats;
-  try {
-    stat = await fs.stat(lockPath);
-  } catch (err: any) {
-    // Race: lock vanished while we inspected it. Retry the open immediately.
-    if (err?.code === "ENOENT") return true;
-    throw err;
-  }
-  if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) return false;
-
-  // Stale — the holder's heartbeat is silent. Claim via atomic rename; only one
-  // racer wins, the rest get ENOENT and fall back to retrying the open.
-  const tombstone = `${lockPath}.stale.${process.pid}.${stat.mtimeMs}`;
-  try {
-    await fs.rename(lockPath, tombstone);
-  } catch (err: any) {
-    if (err?.code === "ENOENT") return true; // another waiter reclaimed it first
-    throw err;
-  }
-  await fs.rm(tombstone, { force: true });
-  return true;
-}
-
 async function runPackageManager(cwd: string, args: string[]): Promise<void> {
   try {
     await execFileAsync(PACKAGE_MANAGER, args, { cwd, maxBuffer: 32 * 1024 * 1024, env: hostEnv() });
@@ -1135,10 +933,6 @@ export const __testing__ = {
   resolveExportTargetValue,
   tryResolveFile,
   computeInstallRoot,
-  withInstallLock,
-  reclaimIfStale,
-  LOCK_STALE_MS,
-  LOCK_HEARTBEAT_MS,
   EXPORTS_MAX_DEPTH,
   DEFAULT_RESOLVER_CONDITIONS,
   REALM_COLLAPSE_NAMES,

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -14,6 +14,7 @@ import {
   inheritedCapability,
   type DefResolver,
 } from "@telorun/analyzer";
+import type { ModuleArtifact } from "../../bundle/module-artifact.js";
 import { ControllerLoader } from "../../controller-loader.js";
 import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
 import { createTemplateController } from "./resource-template-controller.js";
@@ -162,10 +163,18 @@ class ResourceDefinition implements ResourceInstance {
     // `controllers:` candidate fails fast at boot), but defer the expensive
     // import/eval and the controller's `register()` to the kind's first
     // instantiation. Definitions whose kind is never instantiated never import.
+    // The artifact of the module that DECLARED this kind — a bundled controller
+    // ships in its own module's payload, not the consumer's. It owns the pinned
+    // ref and the verified layer index, so the loader picks a candidate and asks
+    // it for that selector's directory rather than fetching anything itself.
+    const artifact = (ctx as unknown as ModuleArtifactHost).getModuleArtifact?.(
+      this.resource.metadata.source,
+    );
     const resolved = await loader.resolve(
       this.resource.controllers,
       this.resource.metadata.source,
       ctx.getControllerPolicy(),
+      artifact,
     );
     ctx.registerDefinition(this.resource);
 
@@ -198,6 +207,16 @@ class ResourceDefinition implements ResourceInstance {
   }
 }
 
+/**
+ * Kernel-internal hook for reaching a module's artifact handle. Off the SDK
+ * surface deliberately: it hands back a kernel class, and only controller
+ * resolution needs it — module authors reach a module's files through
+ * `ctx.resolveModuleFile`, which returns a plain URI.
+ */
+interface ModuleArtifactHost {
+  getModuleArtifact?(source: string | undefined): ModuleArtifact | undefined;
+}
+
 /**
  * Kernel-internal hook the concrete `ResourceContextImpl` exposes for lazy
  * controller loading — deliberately off the public SDK `ResourceContext`

package/src/controllers/resource-definition/resource-inherited-controller.ts

@@ -66,33 +66,89 @@ function resolveRefSlot(value: unknown, ctx: ResourceContext): ResourceInstance
   return instance ?? undefined;
 }
 
-/** Expand a `base:` node against `self`. Self-only CEL resolves to literals now;
- *  a pure `self.<path>` access is navigated directly so live instances pass
- *  through. */
-function expandBaseNode(value: unknown, self: Record<string, unknown>, ctx: EvaluationContext): unknown {
+/** Expand a mapping node against a CEL scope. `self`-only CEL resolves to
+ *  literals now; a pure `self.<path>` access is navigated directly so live
+ *  instances pass through (CEL's output type checker rejects them). Shared by
+ *  `base:` (construction, scope `{ self }`) and the dispatch mappings
+ *  `inputs:` / `result:` (scope `{ self, inputs }` / `{ self, result }`). */
+function expandMappingNode(
+  value: unknown,
+  scope: Record<string, unknown>,
+  ctx: EvaluationContext,
+): unknown {
   if (isCompiledValue(value)) {
     const src = typeof value.source === "string" ? value.source.trim() : "";
     const m = src.match(SELF_PATH);
     if (m) {
-      let cur: unknown = self;
+      let cur: unknown = scope.self;
       for (const key of m[1].split(".").slice(1)) {
         cur = (cur as Record<string, unknown> | undefined)?.[key];
       }
       return cur;
     }
-    return ctx.expandWith(value, { self });
+    return ctx.expandWith(value, scope);
   }
-  if (Array.isArray(value)) return value.map((v) => expandBaseNode(v, self, ctx));
+  if (Array.isArray(value)) return value.map((v) => expandMappingNode(v, scope, ctx));
   if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      out[k] = expandBaseNode(v, self, ctx);
+      out[k] = expandMappingNode(v, scope, ctx);
     }
     return out;
   }
   return value;
 }
 
+/**
+ * Bind the dispatch mappings of a child that REPLACED its inherited contract.
+ *
+ * A contract resolves to the nearest declaration along `extends` and never
+ * merges, so a child declaring `inputType` presents a signature the inherited
+ * controller has never heard of. `inputs:` is the adapter that turns the child's
+ * signature into the parent's call, and `result:` turns the parent's result back
+ * into the child's declared output — the same top-level-sibling factoring a
+ * template definition uses for `invoke:`.
+ *
+ * Bound onto the parent instance rather than wrapping it, so the child still IS
+ * a parent instance: `init`, `snapshot`, `teardown` and status plumbing are
+ * untouched, and nothing new appears in a declared ref slot. It composes with
+ * the kernel's contract binding by position — the parent's contract was bound
+ * when the parent instance was produced, this mapping goes on next, and the
+ * child's own contract is bound outermost by the caller. One dispatch therefore
+ * checks the child's inputs, maps, checks the parent's inputs, runs, checks the
+ * parent's result, maps back, and checks the child's result.
+ */
+function bindDispatchMapping(
+  instance: ResourceInstance,
+  definition: ResourceDefinition,
+  self: Record<string, unknown>,
+  ctx: EvaluationContext,
+): void {
+  const body = definition as unknown as { inputs?: unknown; result?: unknown };
+  const inputsMapping = body.inputs;
+  const resultMapping = body.result;
+  if (inputsMapping == null && resultMapping == null) return;
+  if (typeof instance.invoke !== "function") return;
+
+  // Every argument is forwarded — the mapping rewrites `inputs`, while the
+  // InvokeContext (cancellation, tracing) in later parameters belongs to the
+  // caller and must reach the inherited controller untouched.
+  const original = instance.invoke.bind(instance) as (
+    inputs: any,
+    ...rest: unknown[]
+  ) => Promise<unknown>;
+  instance.invoke = async (inputs: any, ...rest: unknown[]) => {
+    const mappedInputs =
+      inputsMapping != null
+        ? (expandMappingNode(inputsMapping, { self, inputs }, ctx) as Record<string, unknown>)
+        : inputs;
+    const result = await original(mappedInputs, ...rest);
+    return resultMapping != null
+      ? expandMappingNode(resultMapping, { self, result }, ctx)
+      : result;
+  };
+}
+
 /**
  * Controller for a definition that inherits its controller by delegation — it
  * `extends` a concrete kind, declares no own `controllers:` / template body, and
@@ -143,7 +199,7 @@ export function createInheritedController(
       // instances in `self`), minus the reserved keys.
       let parentConfig: Record<string, unknown>;
       if (base != null) {
-        parentConfig = expandBaseNode(base, self, definingContext) as Record<string, unknown>;
+        parentConfig = expandMappingNode(base, { self }, definingContext) as Record<string, unknown>;
       } else {
         const { kind: _kind, metadata: _metadata, name: _name, ...config } = self;
         parentConfig = config;
@@ -159,7 +215,10 @@ export function createInheritedController(
           `Telo.Definition '${definition.metadata.name}': inherited controller requires a ResourceContext host that implements createInheritedInstance().`,
         );
       }
-      return host.createInheritedInstance(definingContext, parentResource);
+      const instance = await host.createInheritedInstance(definingContext, parentResource);
+      if (!instance) return null;
+      bindDispatchMapping(instance, definition, self, definingContext);
+      return instance;
     },
   };
 }

package/src/controllers/type/json-schema-controller.ts

@@ -0,0 +1,114 @@
+import { evaluate } from "@marcbachmann/cel-js";
+import type {
+  ResourceContext,
+  ResourceInstance,
+  ResourceManifest,
+  TypeRule,
+} from "@telorun/sdk";
+import { canonicalTypeSchemaId, mergeTypeSchemas, RuntimeError } from "@telorun/sdk";
+
+/**
+ * `Telo.JsonSchema` — a named data shape.
+ *
+ * It lives in the kernel rather than in an installable module for the same
+ * reason the mandatory log sinks do: declaring a shape is not optional. Every
+ * kind that carries an invocation contract needs one, so requiring an import to
+ * write `inputType:` would tax the exact thing contracts want authors to do —
+ * and a library declaring its own contract would have to import a module purely
+ * to describe itself.
+ *
+ * `type.JsonSchema` is retained as a deprecated alias with the same behaviour, so
+ * published manifests keep resolving.
+ */
+class JsonSchemaType {
+  constructor(
+    private readonly qualifiedName: string,
+    private readonly rules: TypeRule[],
+    /** The fully-resolved (post-`extends`), self-contained JSON Schema. Read by
+     *  consumers that need the effective shape — e.g. a templated resource
+     *  threading `${{ self.model.schema }}` into a request validation schema. */
+    readonly schema: Record<string, unknown>,
+  ) {}
+
+  /**
+   * Validate data against this type's CEL rules — the invariant layer on top of
+   * the schema itself, which AJV enforces through the schema registry.
+   */
+  validateRules(data: unknown): void {
+    for (const rule of this.rules) {
+      let result: unknown;
+      try {
+        result = evaluate(rule.condition, { this: data });
+      } catch (err) {
+        throw new RuntimeError(
+          "ERR_TYPE_VALIDATION_FAILED",
+          `Type "${this.qualifiedName}" rule evaluation failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (result !== true) {
+        throw new RuntimeError(
+          rule.code,
+          rule.message ??
+            `Type "${this.qualifiedName}" validation failed: rule "${rule.code}" not satisfied`,
+        );
+      }
+    }
+  }
+}
+
+/** A type resource is pure declaration: it registers a schema and holds the
+ *  resolved shape, implementing none of the lifecycle verbs. `ResourceInstance`
+ *  is entirely optional members, so a class with none of them satisfies it only
+ *  by assertion — the same shape the module-loaded controller had, where the
+ *  dynamic-import boundary erased the type instead of asserting it. */
+export async function create(
+  resource: ResourceManifest,
+  ctx: ResourceContext,
+): Promise<ResourceInstance | null> {
+  const qualifiedName = `${resource.metadata.module}.${resource.metadata.name}`;
+  const ownSchema = resource.schema as Record<string, unknown>;
+
+  let schema: Record<string, unknown> = ownSchema;
+
+  const extendsField = resource.extends as string | string[] | undefined;
+  if (extendsField) {
+    const parents = Array.isArray(extendsField) ? extendsField : [extendsField];
+
+    const parentSchemas: Record<string, unknown>[] = [];
+    for (const parent of parents) {
+      const parentSchema = ctx.lookupSchema(parent);
+      // Defer if any parent schema isn't registered yet (multi-pass resolution).
+      if (!parentSchema) return null;
+      parentSchemas.push(parentSchema as Record<string, unknown>);
+    }
+
+    // Each parent's registered schema is itself already resolved, so merging
+    // them makes inheritance transitive through grandparents with no `$ref`s
+    // left in the result.
+    schema = mergeTypeSchemas([...parentSchemas, ownSchema]);
+  }
+
+  const rules = (Array.isArray(resource.rules) ? resource.rules : []) as TypeRule[];
+
+  ctx.registerSchema(qualifiedName, schema);
+  ctx.registerTypeRules(qualifiedName, rules);
+
+  // Also register under the short name so types can be referenced without a
+  // module prefix.
+  const shortName = resource.metadata.name;
+  if (shortName !== qualifiedName) {
+    ctx.registerSchema(shortName, schema);
+    ctx.registerTypeRules(shortName, rules);
+  }
+
+  // Canonical module-scoped id — the target of `$ref: "telo://Self/<name>"` (and
+  // `telo://<Alias>/<name>` across imports) once the loader resolves the
+  // authority to this module. Authority-free, so a validator can actually
+  // resolve the reference; see `canonicalTypeSchemaId`.
+  const moduleName = resource.metadata.module as string | undefined;
+  if (moduleName) {
+    ctx.registerSchema(canonicalTypeSchemaId(moduleName, shortName), schema);
+  }
+
+  return new JsonSchemaType(qualifiedName, rules, schema) as unknown as ResourceInstance;
+}