@telorun/kernel 0.46.0 → 0.48.0

package/dist/transports/transport.d.ts

@@ -86,6 +86,25 @@ export interface Transport {
      *  re-pushed to different bytes — so the discovery tracker records this
      *  digest per version and re-checks it on every track. */
     digest(ref: string): Promise<string | null>;
+    /** Telo's inline integrity hash (`sha256-<base64url>`) for the `telo.yaml`
+     *  `ref` resolves to — the value written as a `#sha256-…` pin by `telo
+     *  publish` and re-pinned by `telo upgrade`. Throws when the ref does not
+     *  resolve; callers decide whether that is fatal (`--frozen`) or best-effort.
+     *
+     *  This is on the interface, not computed by the caller, because *what gets
+     *  hashed* is transport-specific and must match exactly what that transport's
+     *  own `source.read()` verifies — otherwise a pin written at publish fails
+     *  verification at import. HTTP/registry hash the raw response bytes;
+     *  OCI hashes the UTF-8 encoding of the `telo.yaml` extracted from the tar
+     *  layer. A caller cannot know which, so a caller-side scheme branch silently
+     *  degrades the moment a transport is added — which is exactly how `oci://`
+     *  refs came to be published unpinned.
+     *
+     *  Distinct from `digest()`: that is an opaque transport-native content id for
+     *  change detection, never written into a manifest or compared across
+     *  transports. This is the portable, cross-transport hash Telo itself
+     *  verifies. */
+    manifestHash(ref: string): Promise<string>;
     /** Push `bundle` to `destination` (a base ref / repo whose scheme this
      *  transport owns), pinning the payload and writing the transport-native
      *  artifact shape. Throws on failure. Used by `telo publish`. */

package/dist/transports/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;sDAGsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;;iEAIiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;kFAEkF;AAClF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6CACyC;IACzC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;yDAYyD;AACzD,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/B;;gFAE4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;6EAEyE;IACzE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAE5C;;;6BAGyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAEpD;;;kFAG8E;IAC9E,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAErD;;;;;;;8DAO0D;IAC1D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5C;;qEAEiE;IACjE,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;2BAKuB;IACvB,sBAAsB,CACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,eAAe,GACvB,MAAM,CAAC;CACX"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;sDAGsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;;iEAIiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;kFAEkF;AAClF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6CACyC;IACzC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;yDAYyD;AACzD,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/B;;gFAE4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;6EAEyE;IACzE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAE5C;;;6BAGyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAEpD;;;kFAG8E;IAC9E,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAErD;;;;;;;8DAO0D;IAC1D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5C;;;;;;;;;;;;;;;;;oBAiBgB;IAChB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE3C;;qEAEiE;IACjE,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;2BAKuB;IACvB,sBAAsB,CACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,eAAe,GACvB,MAAM,CAAC;CACX"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.36.0",
+    "@telorun/analyzer": "0.38.0",
     "@telorun/glob": "0.2.0",
     "@telorun/templating": "0.10.1",
     "ajv": "^8.17.1",
@@ -61,7 +61,7 @@
     "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.44.0"
+    "@telorun/sdk": "0.48.0"
   },
   "optionalDependencies": {
     "esbuild": "^0.28.1"

package/src/application-env.ts

@@ -1,4 +1,5 @@
-import { residualEntrySchema } from "@telorun/analyzer";
+import { type DefResolver, effectiveAuthorSchema, residualEntrySchema } from "@telorun/analyzer";
+import type { ResourceDefinition } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import { SchemaValidator } from "./schema-validator.js";
 
@@ -145,24 +146,39 @@ export function precompileApplicationEnvSchemas(
 
 /**
  * Build-time cache warm for resource-config validators. The runtime
- * `_createInstance` compiles `controller.schema` — which falls back to the
- * declaring `Telo.Definition`'s own `schema` — to validate every resource's
- * config, then validates inputs/outputs against `inputType` / `outputType`.
- * The analyze-only warm pass stops before instantiation, so without this those
- * validators are absent from the `__validators` cache and the runtime
- * recompiles (and, on a read-only image, fails to persist) them on every boot.
+ * `_createInstance` compiles the declaring `Telo.Definition`'s `schema` to
+ * validate every resource's config, then validates inputs/outputs against
+ * `inputType` / `outputType`. The analyze-only warm pass stops before
+ * instantiation, so without this those validators are absent from the
+ * `__validators` cache and the runtime recompiles (and, on a read-only image,
+ * fails to persist) them on every boot.
  *
  * Compiling each definition's `schema` (plus any inline `inputType` /
  * `outputType` object schemas) here writes them into the same content-addressed
  * cache the runtime reads, keyed identically because the same schema object is
- * fed to the same `validator.compile`. Definitions whose controller exports its
- * own `schema` (rare) still recompile at runtime — that needs the controller
- * loaded, which the warm pass does not do. Compile failures are swallowed; a
- * genuinely broken schema surfaces through analysis / runtime, not here.
+ * fed to the same `validator.compile`. Every kind is bakeable now that the
+ * manifest is the sole config contract — a controller can no longer supply a
+ * schema the warm cannot see. Compile failures are swallowed; a genuinely
+ * broken schema surfaces through analysis / runtime, not here.
+ *
+ * `resolverFor` bakes the INHERITANCE-RESOLVED schema too. A `base:`-less
+ * `extends` child is validated at runtime against `merge(parent, own)` — a
+ * different object than its raw `schema:`, so a different cache key. Without
+ * this the warm bakes a schema the runtime never asks for and every inheriting
+ * kind misses on every boot, recompiling (and, on a read-only image, failing to
+ * persist) forever. Both forms are compiled — the raw one still backs
+ * definitions that don't inherit.
+ *
+ * It is a factory, not a single resolver, because `extends` aliases are scoped
+ * to the DECLARING module — `Cache.Store` reads against that library's import
+ * map, `Self.Host` against its own name. A global resolver silently fails to
+ * resolve those, yielding the un-merged schema and reintroducing the very miss
+ * this exists to prevent.
  */
 export function precompileDefinitionSchemas(
   manifests: Array<Record<string, any>>,
   validator: SchemaValidator,
+  resolverFor?: (def: Record<string, any>) => DefResolver,
 ): void {
   const compile = (schema: unknown): void => {
     if (!schema || typeof schema !== "object") return;
@@ -177,6 +193,15 @@ export function precompileDefinitionSchemas(
     compile(m.schema);
     compile(m.inputType);
     compile(m.outputType);
+    if (resolverFor && m.extends) {
+      // Mirrors the runtime stamp in `resource-definition-controller`; sharing
+      // `effectiveAuthorSchema` is what keeps the two keys identical.
+      try {
+        compile(effectiveAuthorSchema(m as unknown as ResourceDefinition, resolverFor(m)));
+      } catch {
+        // An unresolvable parent is a diagnostic elsewhere; the warm just skips.
+      }
+    }
   }
 }
 

package/src/bundle/module-manifest.ts

@@ -27,6 +27,12 @@ export interface OwnerManifest {
   filesIntegrity?: string;
   /** True when the owner doc declares a non-empty `files:` list. */
   declaresFiles: boolean;
+  /** Descriptive provenance a transport projects into its backend's metadata
+   *  (OCI annotations). Never used to address the artifact. */
+  description?: string;
+  repository?: string;
+  license?: string;
+  documentation?: string;
 }
 
 /** Read the owner doc's identity + payload fields from a manifest, parsing once
@@ -45,5 +51,9 @@ export function readOwnerManifest(text: string): OwnerManifest {
     version: str(md.version),
     filesIntegrity: str(parsed?.filesIntegrity),
     declaresFiles: Array.isArray(parsed?.files) && parsed.files.length > 0,
+    description: str(md.description),
+    repository: str(md.repository),
+    license: str(md.license),
+    documentation: str(md.documentation),
   };
 }

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

@@ -547,6 +547,52 @@ 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>): Promise<T> {
+  return withLocalInstallQueue(installRoot, () => withFileInstallLock(installRoot, fn));
+}
+
 /**
  * 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
@@ -565,7 +611,7 @@ async function resolveKernelPackageRoot(name: string): Promise<string | null> {
  * 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 withInstallLock<T>(installRoot: string, fn: () => Promise<T>): Promise<T> {
+async function withFileInstallLock<T>(installRoot: string, fn: () => Promise<T>): Promise<T> {
   const lockPath = path.join(installRoot, ".lock");
 
   await fs.mkdir(installRoot, { recursive: true });

package/src/controller-registry.ts

@@ -111,18 +111,17 @@ export class ControllerRegistry {
   }
 
   /**
-   * Distinct controller `schema` objects across all registered kinds (one per
-   * kind, default fingerprint preferred). Used by the build-time validator warm
-   * to pre-compile the framework/builtin controller schemas (`Telo.Import`,
-   * `Telo.Definition`, the module controller, …) the runtime validates
-   * resources against — module-defined kinds aren't registered here until
-   * instantiation, so those are warmed from the static manifests instead.
+   * Distinct resource-config schemas across all registered kinds, taken from
+   * each kind's DEFINITION. Used by the build-time validator warm to pre-compile
+   * the framework/builtin schemas (`Telo.Import`, `Telo.Definition`, the module
+   * controller, …) the runtime validates resources against — module-defined
+   * kinds aren't registered here until instantiation, so those are warmed from
+   * the static manifests instead.
    */
   getControllerSchemas(): object[] {
     const schemas: object[] = [];
-    for (const byFp of this.controllersByKind.values()) {
-      const controller = byFp.get(DEFAULT_FINGERPRINT) ?? byFp.values().next().value;
-      const schema = controller?.schema;
+    for (const kind of this.controllersByKind.keys()) {
+      const schema = this.definitionsByKind.get(kind)?.schema;
       if (schema && typeof schema === "object") schemas.push(schema);
     }
     return schemas;
@@ -142,9 +141,14 @@ export class ControllerRegistry {
       throw new Error(`Cannot register controller for kind ${kind} without definition`);
     }
     const definition = this.definitionsByKind.get(kind);
+    // The DEFINITION's schema is the resource-config contract, always. A
+    // controller module's exports become the controller instance verbatim, so a
+    // stray `export const schema` used to silently override the manifest — the
+    // analyzer never loads controllers, so those overrides were invisible to
+    // `telo check`, unbakeable by the validator warm, and free to drift from the
+    // manifest they shadowed.
     const wrappedController: ControllerInstance = {
       ...controller,
-      schema: controller.schema ?? definition?.schema,
       inputType: controller.inputType,
       outputType: controller.outputType,
     };

package/src/controllers/module/import-controller.ts

@@ -155,7 +155,7 @@ export async function create(
   // A library references its own kinds via `Self.<Kind>` (e.g. when it declares an
   // instance to export). Register `Self` → the library's own module in the child context
   // so those resolve at runtime — ungated, since this is internal use, not an importer.
-  childCtx.registerImport("Self", targetModule, []);
+  childCtx.registerUngatedAlias("Self", targetModule);
 
   // Stamp the resolved controller policy on the child only when the import
   // specifies a `runtime:` field that resolves to something other than the
@@ -216,8 +216,16 @@ export async function create(
   // of an imported library's kind). `parseExportEntry` (shared with the analyzer) yields
   // `{name, alias?}` — `name` is the exported kind suffix, `alias` (when set) names this
   // library's own import it re-exports from.
-  const kindEntries = ((moduleManifest.exports?.kinds ?? []) as string[]).map(parseExportEntry);
-  const exportedKindSuffixes = kindEntries.map((k) => k.name);
+  // A library that declares `exports.kinds` is gated to exactly that list (an empty list
+  // exports nothing). One that declares none registers an unrestricted gate (`undefined`)
+  // — the legacy permissive default, kept so already-published module versions, whose
+  // manifests can no longer gain an `exports.kinds` block, stay importable. Flipping this
+  // to a gated `[]` makes kinds private by default and is a breaking change for every such
+  // version; it needs the ecosystem republished with explicit exports first.
+  const declaredKinds = moduleManifest.exports?.kinds as string[] | undefined;
+  const kindEntries = (declaredKinds ?? []).map(parseExportEntry);
+  const exportedKindSuffixes =
+    declaredKinds === undefined ? undefined : kindEntries.map((k) => k.name);
   // `exports.resources` entries are a bare name (`Db`, a locally-owned export) or a dotted
   // `Alias.Name` (re-export of an imported instance, under name `Name`) — same grammar as
   // `exports.kinds`.
@@ -324,30 +332,3 @@ function validateRequiredInputs(
   }
 }
 
-export const schema = {
-  type: "object",
-  properties: {
-    kind: { type: "string" },
-    metadata: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        module: { type: "string" },
-      },
-      required: ["name"],
-      additionalProperties: true,
-    },
-    source: { type: "string" },
-    integrity: { type: "string" },
-    variables: { type: "object" },
-    secrets: { type: "object" },
-    runtime: {
-      oneOf: [
-        { type: "string" },
-        { type: "array", items: { type: "string" } },
-      ],
-    },
-  },
-  required: ["metadata", "source"],
-  additionalProperties: false,
-};

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

@@ -50,7 +50,3 @@ export async function create(resource: any, _ctx: ResourceContext): Promise<Reso
   return new ResourceAbstract(resource as unknown as ResourceAbstractResource);
 }
 
-export const schema = {
-  type: "object",
-  additionalProperties: true,
-};

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

@@ -213,7 +213,3 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   return new ResourceDefinition(definition);
 }
 
-export const schema = {
-  type: "object",
-  additionalProperties: true,
-};

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

@@ -125,8 +125,6 @@ export function createInheritedController(
   }
 
   return {
-    schema: authorSchema,
-
     create: async (resource: any, ctx: ResourceContext): Promise<ResourceInstance | null> => {
       const self: Record<string, unknown> = { ...resource, name: resource.metadata.name };
       for (const path of refFieldPaths) {

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

@@ -61,8 +61,6 @@ export function createTemplateController(definition: {
   result?: Record<string, any>;
 }, definingContext: EvaluationContext): ControllerInstance {
   return {
-    schema: definition.schema ?? { type: "object", additionalProperties: true },
-
     create: async (resource: any, ctx: ResourceContext): Promise<ResourceInstance> => {
       // `self` is read lazily: Phase 5 injection mutates `resource`'s ref slots
       // (e.g. `connection: !ref Db` → the live instance) AFTER create() but before

package/src/kernel.ts

@@ -276,7 +276,7 @@ export class Kernel implements IKernel {
   private async loadBuiltinDefinitions(): Promise<void> {
     // Declare built-in module namespaces upfront so getContext() can distinguish
     // "not yet populated" from a completely unknown module name.
-    this.rootContext.registerImport("Telo", "Telo", []); // built-ins, unrestricted
+    this.rootContext.registerUngatedAlias("Telo", "Telo"); // built-ins — no import boundary
 
     // Register built-in definitions with the controller registry.
     // AnalysisRegistry's underlying DefinitionRegistry already seeds KERNEL_BUILTINS on construction.
@@ -483,13 +483,17 @@ export class Kernel implements IKernel {
         );
       }
       // Bake the per-kind resource-config validators too. `_createInstance`
-      // compiles `controller.schema` (which falls back to the definition's own
-      // `schema`) for every resource at runtime — work this analyze-only pass
-      // otherwise skips because it stops before instantiation, leaving the
-      // runtime to recompile and fail to persist them on a read-only image.
+      // compiles the definition's `schema` for every resource at runtime — work
+      // this analyze-only pass otherwise skips because it stops before
+      // instantiation, leaving the runtime to recompile and fail to persist
+      // them on a read-only image.
       // Pre-compiling every `Telo.Definition` schema here writes them into the
-      // same content-addressed `__validators/` cache the runtime reads.
-      precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator);
+      // 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.
+      precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator, (def) =>
+        this.registry.resolverForDefinition(def),
+      );
       // Framework/builtin controller schemas (`Telo.Import`, `Telo.Definition`,
       // the module controller, …) aren't in the static manifests but are
       // validated per-resource at runtime just the same. They're registered by
@@ -1040,12 +1044,17 @@ export class Kernel implements IKernel {
         `Controller for ${kind} does not implement create method`,
       );
     }
-    if (!controller.schema?.type) {
-      throw new Error(`No schema defined for ${kind} controller`);
+    // The DEFINITION is the sole resource-config contract — a controller module
+    // cannot supply or override one. Keeping the schema on the manifest is what
+    // lets `telo check` see it, the validator warm bake it, and the editor render
+    // it; a code-side schema was invisible to all three and free to drift.
+    const definition = this.controllers.getDefinition(resolvedKind);
+    const configSchema = definition?.schema as Record<string, unknown> | undefined;
+    if (!configSchema?.type) {
+      throw new Error(`No schema defined for kind ${kind}`);
     }
 
     // Resolve eval paths from x-telo-eval annotations in the parent and own schema
-    const definition = this.controllers.getDefinition(resolvedKind);
     const parentDef = definition?.capability
       ? this.controllers.getDefinition(definition.capability)
       : undefined;
@@ -1063,8 +1072,8 @@ export class Kernel implements IKernel {
     // restoring the pre-CEL string view that the schema expects.
     try {
       this.sharedSchemaValidator
-        .compile(controller.schema)
-        .validate(stripCompiledValues(resource, controller.schema as Record<string, unknown>));
+        .compile(configSchema)
+        .validate(stripCompiledValues(resource, configSchema));
     } catch (error) {
       throw new RuntimeError(
         "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",

package/src/module-context.ts

@@ -72,7 +72,13 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   /** Maps import alias → real module name for kind resolution. */
   private readonly importAliases = new Map<string, string>();
 
-  /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
+  /** Maps import alias → allowed kind names, i.e. the target's `exports.kinds` gate.
+   *  A registered set is authoritative: only listed kinds resolve, and an empty set
+   *  exports nothing. An absent entry is unrestricted, which today covers two cases —
+   *  `registerUngatedAlias` (aliases crossing no import boundary: `Self`, the `Telo`
+   *  built-ins) and an import whose target declares no `exports.kinds` at all (the
+   *  legacy permissive default, kept so already-published module versions stay
+   *  importable). Only the latter disappears when kinds go private by default. */
   private readonly importedKinds = new Map<string, Set<string>>();
 
   /** Maps import alias → its child context's exported instances. Registered by the
@@ -191,16 +197,34 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   }
 
   /**
-   * Register an imported module under the given alias, with the list of kind names
-   * it exports. An empty kinds array means no restriction (used for built-ins like Telo).
+   * Register an imported module under the given alias, gated to the kind names it
+   * exports (its `exports.kinds`). Only listed kinds resolve; an empty list exports
+   * nothing.
+   *
+   * `kinds` is `undefined` for exactly one case: the target declares no `exports.kinds`
+   * at all, the legacy permissive default that keeps already-published module versions
+   * importable. Every such call is a site to delete when kinds go private by default —
+   * for an alias that crosses no import boundary use `registerUngatedAlias` instead, so
+   * the two never get confused.
    */
-  registerImport(alias: string, targetModule: string, kinds: string[]): void {
+  registerImport(alias: string, targetModule: string, kinds?: readonly string[]): void {
     this.importAliases.set(alias, targetModule);
-    if (kinds.length > 0) {
+    if (kinds !== undefined) {
       this.importedKinds.set(alias, new Set(kinds));
     }
   }
 
+  /**
+   * Register an alias that crosses no import boundary and is therefore never gated:
+   * `Self` (a library resolving its own kinds — `exports.kinds` gates importers, not
+   * internal use) and the `Telo` built-in namespace. Distinct from an ungated
+   * `registerImport` so that making kinds private by default cannot accidentally gate
+   * these to nothing, which would break every built-in kind everywhere.
+   */
+  registerUngatedAlias(alias: string, targetModule: string): void {
+    this.importAliases.set(alias, targetModule);
+  }
+
   /** Register an import alias's exported instances for cross-module reference resolution.
    *  `names` is the gate (the import's `exports.resources`); `terminal` returns the child
    *  context's pre-flattened terminal getter for a name (existing only after the import's
@@ -398,7 +422,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     // Re-export override: if this import's exported-kind table maps the suffix to a DIFFERENT
     // owning module, the kind is transitively re-exported (`exports.kinds: [Alias.Kind]`) —
     // resolve to its true owner. A local kind maps to `${realModule}.${suffix}` (no override),
-    // and a module without `exports.kinds` has an empty table (unrestricted, unchanged). Built
+    // and a module without `exports.kinds` has an empty table (nothing re-exported). Built
     // deferred, so before the import inits this returns the un-overridden kind, whose controller
     // miss makes the init loop retry until the table is ready.
     const reExported = this.importedKindResolvers.get(prefix)?.(suffix);

package/src/resource-context.ts

@@ -466,7 +466,9 @@ export class ResourceContextImpl implements ResourceContext {
     await this.kernel.emitRuntimeEvent(event, payload);
   }
 
-  registerModuleImport(alias: string, targetModule: string, kinds: string[]): void {
+  /** `kinds` is the target's `exports.kinds` gate; omit it for an unrestricted alias
+   *  (one crossing no import boundary). See `ModuleContext.registerImport`. */
+  registerModuleImport(alias: string, targetModule: string, kinds?: readonly string[]): void {
     this.moduleContext.registerImport(alias, targetModule, kinds);
   }
 

package/src/transports/oci/oci-client.ts

@@ -32,6 +32,11 @@ export interface OciManifest {
   artifactType?: string;
   config: OciDescriptor;
   layers: OciDescriptor[];
+  /** Descriptive key/value metadata on the manifest. Telo projects the module's
+   *  declared provenance into the standard `org.opencontainers.image.*` keys —
+   *  the only metadata channel GHCR exposes, since it does not serve the
+   *  referrers API. */
+  annotations?: Record<string, string>;
 }
 
 function sha256Hex(bytes: Uint8Array): string {

package/src/transports/oci/oci-transport.ts

@@ -1,12 +1,13 @@
 import {
   DEFAULT_MANIFEST_FILENAME,
   IntegrityError,
+  sha256Base64Url,
   verifyIntegrity,
   type ManifestSource,
 } from "@telorun/analyzer";
 
 import { computeFilesIntegrity, injectFilesIntegrity } from "../../bundle/files-integrity.js";
-import { readOwnerManifest } from "../../bundle/module-manifest.js";
+import { readOwnerManifest, type OwnerManifest } from "../../bundle/module-manifest.js";
 import { makeTarGz, readTarGz, toPayloadFiles } from "../../bundle/tar.js";
 import type {
   FetchedArtifact,
@@ -134,6 +135,39 @@ export class OciTransport implements Transport {
     return pullVerified(ref);
   }
 
+  /** Hashes the **UTF-8 encoding of the extracted `telo.yaml`**, which is what
+   *  `pullVerified` checks an inline `#sha256-…` pin against on the read path.
+   *
+   *  Cost note: a module is one tar blob, so there is no way to read `telo.yaml`
+   *  without pulling the whole artifact — including any `files:` payload — and
+   *  this path is deliberately uncached (a pin must hash what is published
+   *  *now*, not a cached copy). Two consequences for callers: pinning N imports
+   *  costs N full artifact pulls, and `pullVerified` also re-checks the
+   *  dependency's `filesIntegrity`, so a corrupt *payload* upstream surfaces
+   *  here as a pinning failure rather than a payload error. Both are acceptable
+   *  for publish-time pinning, where correctness beats latency and refusing to
+   *  pin against a corrupt dependency is the right outcome. */
+  async manifestHash(ref: string): Promise<string> {
+    const { manifest } = await pullVerified(ref);
+    return `sha256-${await sha256Base64Url(new TextEncoder().encode(manifest))}`;
+  }
+
+  /** Project a module's declared provenance onto the standard
+   *  `org.opencontainers.image.*` annotation keys. Descriptive only — nothing
+   *  addresses the artifact by these. Absent fields are omitted rather than
+   *  written empty, so the manifest carries only what the module declared. */
+  private static annotationsFor(identity: OwnerManifest): Record<string, string> {
+    const mapped: Array<[string, string | undefined]> = [
+      ["org.opencontainers.image.title", identity.name],
+      ["org.opencontainers.image.version", identity.version],
+      ["org.opencontainers.image.description", identity.description],
+      ["org.opencontainers.image.source", identity.repository],
+      ["org.opencontainers.image.licenses", identity.license],
+      ["org.opencontainers.image.documentation", identity.documentation],
+    ];
+    return Object.fromEntries(mapped.filter((e): e is [string, string] => Boolean(e[1])));
+  }
+
   async publish(
     destination: string,
     bundle: PublishBundle,
@@ -144,19 +178,19 @@ export class OciTransport implements Transport {
       throw new Error("OCI publish requires metadata.version (used as the tag).");
     }
 
-    // Destination is a full repo (`oci://host/repo`) or host-only
-    // (`oci://host`), which defaults the repo to `<namespace>/<name>`.
+    // Destination must be a full repo (`oci://host/repo`). Identity is the ref,
+    // so the repo is never derived from `metadata.namespace`/`name` — a
+    // metadata-derived path is wrong whenever the repo differs from the name,
+    // and would silently push to a namespace the publisher may not own.
     const afterScheme = destination.replace(/^oci:\/\//, "").replace(/\/+$/, "");
     const slash = afterScheme.indexOf("/");
     const host = slash > 0 ? afterScheme.slice(0, slash) : afterScheme;
-    let repo = slash > 0 ? afterScheme.slice(slash + 1) : "";
+    const repo = slash > 0 ? afterScheme.slice(slash + 1) : "";
     if (!repo) {
-      if (!identity.namespace || !identity.name) {
-        throw new Error(
-          `OCI publish to host-only '${destination}' needs metadata.namespace and metadata.name to default the repo.`,
-        );
-      }
-      repo = `${identity.namespace}/${identity.name}`;
+      throw new Error(
+        `OCI publish destination '${destination}' is host-only — it must name a full repository, ` +
+          `e.g. 'oci://${host || "ghcr.io"}/<org>/<name>'.`,
+      );
     }
     const tag = identity.version;
 
@@ -173,12 +207,14 @@ export class OciTransport implements Transport {
     const client = new OciClient(host, repo);
     const layerDigest = await client.pushBlob(tar);
     const config = await client.pushEmptyConfig();
+    const annotations = OciTransport.annotationsFor(identity);
     const manifest: OciManifest = {
       schemaVersion: 2,
       mediaType: OCI_MANIFEST_MEDIA_TYPE,
       artifactType: TELO_LAYER_MEDIA_TYPE,
       config,
       layers: [{ mediaType: TELO_LAYER_MEDIA_TYPE, digest: layerDigest, size: tar.length }],
+      ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
     };
     await client.pushManifest(tag, manifest);