@telorun/analyzer 0.66.0 → 0.67.0

package/src/builtins.ts

@@ -232,6 +232,35 @@ const ROOT_LOGGING_SCHEMA = {
   additionalProperties: false,
 };
 
+/** A `Telo.Library`'s declared resource inputs — the instances it requires from
+ *  whoever imports it, the inward half of the symmetry `exports.resources`
+ *  already had outward. Each entry is constrained by KIND ONLY, through the same
+ *  alias-qualified grammar `extends:` and `x-telo-ref` use; there is no `use:`,
+ *  because the boundary is a dependency edge for init order whatever the library
+ *  does with the instance. See `analyzer/nodejs/src/resource-input.ts`. */
+const LIBRARY_RESOURCE_INPUTS_SCHEMA = {
+  type: "object",
+  additionalProperties: {
+    type: "object",
+    required: ["kind"],
+    properties: {
+      kind: { type: "string" },
+      description: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+};
+
+/** The importer's side of the same block: entry name → `!ref` to the instance
+ *  supplied for it. Left open because the accepted KIND is declared by the
+ *  target library, not by this schema — the constraint is checked by
+ *  `validate-resource-inputs.ts`, which reads the target's declared block off
+ *  the `metadata.requiredResources` stamp. */
+const IMPORT_RESOURCE_INPUTS_SCHEMA = {
+  type: "object",
+  additionalProperties: {},
+};
+
 export const KERNEL_BUILTINS: ResourceDefinition[] = [
   { kind: "Telo.Abstract", metadata: { name: "Template", module: "Telo" } },
   // "Control can be transferred to this" — the parent of Invocable and Runnable,
@@ -427,28 +456,26 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: {
             type: "object",
             additionalProperties: true,
-            // Resource bodies are `self`-only for config: per-call `inputs` is
-            // NOT in scope here. Each entry is a persistent child created once at
-            // init() and reused, so its config cannot depend on call-time data —
-            // that flows through the top-level `inputs:` sibling into the dispatch
-            // target's invoke().
+            // A `resources:` entry is a DECLARATION of another kind, so the
+            // CEL inside it belongs to THAT kind: its `x-telo-context` regions
+            // are rebased under this entry's path and take precedence (they are
+            // deeper), which is what puts `inputs`, `item`, `request`, `steps`
+            // and a `catch:`'s `error` in scope exactly where the nested kind
+            // declares them — see `analyzer/nodejs/src/template-body.ts`.
             //
-            // The exception is CEL the child's OWN controller evaluates later
-            // against a runtime context it owns (e.g. an Http.Api evaluating route
-            // CEL per request). Those `request` / `result` / `steps` / `error`
-            // variables are deferred — the template controller preserves them
-            // untouched (see resource-template-controller.ts) — so they are
-            // exposed here permissively. Their deep shape is the child kind's
-            // concern, not the template's, so they type as open values.
+            // What stays here is `self` alone, in force throughout the entry:
+            // it is how a body reaches the configuration its enclosing template
+            // was given, and no nested kind knows about it. The four names that
+            // used to sit beside it (`request` / `result` / `steps` / `error`)
+            // were a fixed permissive stand-in for the nested kind's own
+            // regions — which is why `error` was offered outside every `catch:`
+            // while `inputs` and `item` were undefined wherever a body actually
+            // reads them.
             "x-telo-context": {
               type: "object",
               additionalProperties: false,
               properties: {
                 self: { "x-telo-context-from-root": "schema" },
-                request: {},
-                result: {},
-                steps: {},
-                error: {},
               },
             },
           },
@@ -611,6 +638,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         integrity: { type: "string" },
         variables: { type: "object" },
         secrets: { type: "object" },
+        resources: IMPORT_RESOURCE_INPUTS_SCHEMA,
         runtime: {
           oneOf: [
             { type: "string" },
@@ -757,6 +785,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                   integrity: { type: "string" },
                   variables: { type: "object" },
                   secrets: { type: "object" },
+                  resources: IMPORT_RESOURCE_INPUTS_SCHEMA,
                   runtime: {
                     oneOf: [
                       { type: "string" },
@@ -872,6 +901,29 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         },
         variables: { type: "object" },
         secrets: { type: "object" },
+        // How many times this library is instantiated in one application.
+        //
+        // `isolated` (the default) is what every published module was written
+        // against: each import declaration builds its own child scope with its
+        // own instances, so two libraries importing a third get two of
+        // everything in it. `shared` makes the library a SINGLETON — every
+        // import of it resolves to one instantiation, owned by the root and
+        // torn down after everything that borrowed it.
+        //
+        // Default `isolated` rather than `shared` — the opposite of the
+        // Application field's — because flipping it would silently collapse
+        // every existing app's resource graph and turn per-import `variables:`
+        // into a conflict. The `exports.kinds` precedent: private-by-default is
+        // the better end state and still needs the ecosystem republished first.
+        lifecycle: {
+          type: "string",
+          enum: ["shared", "isolated"],
+          default: "isolated",
+        },
+        // The inward half of `exports.resources`: instances this library
+        // requires from whoever imports it. Library-only — an Application is a
+        // root with no importer, so it owns its instances outright.
+        resources: LIBRARY_RESOURCE_INPUTS_SCHEMA,
         include: {
           type: "array",
           items: { type: "string" },
@@ -902,6 +954,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                   integrity: { type: "string" },
                   variables: { type: "object" },
                   secrets: { type: "object" },
+                  resources: IMPORT_RESOURCE_INPUTS_SCHEMA,
                   runtime: {
                     oneOf: [
                       { type: "string" },

package/src/cel-scope.ts

@@ -42,6 +42,7 @@ import {
 } from "./kernel-globals.js";
 import { gatherPropertySchemas, resolveLocalRef, walkStepArray } from "./schema-walk.js";
 import { readStepSlot } from "./step-slot.js";
+import { bodyForPath, templateBodies } from "./template-body.js";
 import {
   getManifestItem,
   resolveContextAnnotations,
@@ -415,6 +416,20 @@ export class CelScopeResolver {
   private stepContext: Record<string, any> | undefined;
   private invocationContext: Record<string, any> | undefined;
   private errorScopes: Map<string, Record<string, any>> = new Map();
+  /** The same two facts per `resources:` entry of a `Telo.Definition` — a
+   *  template body is a declaration of ANOTHER kind, so its step body and its
+   *  error branches are that kind's, not the enclosing definition's. */
+  private bodyScopes: Array<{
+    prefix: string;
+    scopePrefix: string;
+    manifest: Record<string, any>;
+    stepContext: Record<string, any> | undefined;
+    errorScopes: Map<string, Record<string, any>>;
+  }> = [];
+  /** The enclosing definition's `self` schema, resolved once per resource. A
+   *  template body's contexts resolve against the BODY, so `self` — the one
+   *  binding anchored on the definition — is substituted before they do. */
+  private selfSchema: Record<string, any> | undefined;
 
   constructor(private readonly inputs: CelScopeInputs) {}
 
@@ -462,6 +477,27 @@ export class CelScopeResolver {
         )
       : undefined;
     this.errorScopes = collectErrorContextScopes(authorSchema);
+    this.selfSchema =
+      m.kind === "Telo.Definition" ? buildSelfSchema(m as Record<string, any>, defs, aliases) : undefined;
+    this.bodyScopes = templateBodies(m, defs, aliases, scopes).map((body) => {
+      const bodySchema = defs.effectiveSchemaOf(body.definition) as Record<string, any> | undefined;
+      return {
+        prefix: body.prefix,
+        scopePrefix: body.scopePrefix,
+        manifest: body.manifest as Record<string, any>,
+        stepContext: bodySchema
+          ? buildStepContextSchema(
+              body.manifest as Record<string, any>,
+              bodySchema,
+              allManifests as Record<string, any>[],
+              defs,
+              aliases,
+              scopes,
+            )
+          : undefined,
+        errorScopes: collectErrorContextScopes(bodySchema),
+      };
+    });
   }
 
   /**
@@ -518,7 +554,14 @@ export class CelScopeResolver {
     const m = site.source;
     let matched: Record<string, any> | undefined = site.contextSchema ?? this.invocationContext;
 
-    if (this.stepContext) {
+    // Inside a template body the step and error regions are the NESTED kind's.
+    // Its `steps` accumulator and its `catch:` branches are declared there, and
+    // the enclosing definition's (there are none) would say nothing about them.
+    const inBody = this.bodyScopes.length > 0 ? bodyForPath(this.bodyScopes, path) : undefined;
+    const stepContext = inBody ? inBody.stepContext : this.stepContext;
+    const errorScopes = inBody ? inBody.errorScopes : this.errorScopes;
+
+    if (stepContext) {
       const base = matched ?? { type: "object", properties: {}, additionalProperties: true };
       matched = {
         ...base,
@@ -535,7 +578,7 @@ export class CelScopeResolver {
           // which is a separate decision from knowing the name is legal.
           inputs: { type: "object", additionalProperties: true },
           ...(base.properties ?? {}),
-          steps: this.stepContext,
+          steps: stepContext,
         },
       };
     }
@@ -543,7 +586,7 @@ export class CelScopeResolver {
     // `error` is only in scope inside an error-bearing branch (e.g. a
     // `catch:` / `finally:`), so it's merged per-path, not resource-wide.
     const errorSchema =
-      this.errorScopes.size > 0 ? errorContextForPath(path, this.errorScopes) : undefined;
+      errorScopes.size > 0 ? errorContextForPath(path, errorScopes) : undefined;
     if (errorSchema) {
       const base = matched ?? { type: "object", properties: {}, additionalProperties: true };
       matched = {
@@ -561,16 +604,49 @@ export class CelScopeResolver {
     }
 
     const { defs, aliases, scopes, allManifests, kernelGlobals } = this.inputs;
-    const manifestItem = site.matchedScope
-      ? getManifestItem(path, site.matchedScope, m as Record<string, any>)
-      : (m as Record<string, any>);
-    const rootForResolver = manifestRootForResolver(
-      m as Record<string, any>,
-      defs,
-      aliases,
-      allManifests as Record<string, any>[],
-      scopes,
-    );
+
+    // A template body's context annotations are the NESTED kind's, and every one
+    // that anchors at a root — `x-telo-context-element-from`,
+    // `-collection-from`, `-from-root`, `x-telo-bindings-from` — means the root
+    // of the DECLARATION they were written for. Resolving them against the
+    // enclosing `Telo.Definition` looked `collection:` up on a document that has
+    // no such field, so `item` typed open and a typo below it went unreported —
+    // the one place a nested declaration did not answer as the same declaration
+    // written at the top level.
+    //
+    // So the path and the scope are rebased into the body and the body becomes
+    // the resolution root. `self` is the single binding that genuinely belongs to
+    // the enclosing definition, and it is substituted below rather than left as
+    // an annotation the rebased root would misread.
+    const body = inBody;
+    const localPath = body ? path.slice(body.prefix.length + 1) : path;
+    const localScope =
+      body && site.matchedScope?.startsWith(`${body.scopePrefix}.`)
+        ? `$.${site.matchedScope.slice(body.scopePrefix.length + 1)}`
+        : body
+          ? undefined
+          : site.matchedScope;
+    const rootManifest = body ? body.manifest : (m as Record<string, any>);
+
+    if (body && this.selfSchema && matched.properties?.self) {
+      matched = {
+        ...matched,
+        properties: { ...matched.properties, self: this.selfSchema },
+      };
+    }
+
+    const manifestItem = localScope
+      ? getManifestItem(localPath, localScope, rootManifest)
+      : rootManifest;
+    const rootForResolver = body
+      ? rootManifest
+      : manifestRootForResolver(
+          m as Record<string, any>,
+          defs,
+          aliases,
+          allManifests as Record<string, any>[],
+          scopes,
+        );
     const resolved = resolveContextAnnotations(matched, manifestItem, {
       manifestRoot: rootForResolver,
       defs,
@@ -578,7 +654,7 @@ export class CelScopeResolver {
       allManifests: allManifests as Record<string, any>[],
     });
     return mergeKernelGlobalsIntoContext(
-      withBindingNames(resolved, m as Record<string, any>),
+      withBindingNames(resolved, rootManifest),
       // Typed in the module that DECLARED this resource — for a manifest
       // forwarded from an imported library, that is its `moduleGlobals` stamp,
       // not the consuming application's block.

package/src/definition-registry.ts

@@ -449,6 +449,42 @@ export class DefinitionRegistry {
     return buildFieldMapAtPath(subSchema, fieldPath);
   }
 
+  /** The kinds a definition descends from DIRECTLY — the same two edges
+   *  `register` feeds into `extendedBy`, read the other way.
+   *
+   *  Both spellings, because either can carry the edge that satisfies a slot:
+   *  `capability:` is the legacy implements-this form, `extends:` the canonical
+   *  one. A consumer walking these by hand would be a second reading of what an
+   *  inheritance edge IS, and the downward index and the upward walk have to
+   *  agree about that forever. */
+  parentsOf(kind: string): string[] {
+    const def = this.defs.get(kind);
+    if (!def) return [];
+    return [def.capability, def.extends].filter(
+      (parent): parent is string => typeof parent === "string" && parent.length > 0,
+    );
+  }
+
+  /** Whether every kind this one descends from is registered.
+   *
+   *  When it is, what the kind implements is FULLY KNOWN: a target it does not
+   *  reach is one it genuinely does not implement, so a mismatch is a verdict.
+   *  When a hop is missing — an unimported abstract, an alias the declaring file
+   *  could not resolve — a mismatch cannot be told from a missing dependency,
+   *  which is the partial context every reference check stays lenient in. */
+  ancestryResolved(kind: string): boolean {
+    const queue = [kind];
+    const seen = new Set<string>();
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      if (!this.defs.has(current)) return false;
+      queue.push(...this.parentsOf(current));
+    }
+    return true;
+  }
+
   /** Returns all definitions that transitively extend the given abstract kind.
    *  Follows the capability chain to any depth (equivalent to instanceof in OOP).
    *  Definitions are included regardless of registration order. */

package/src/dependency-graph.ts

@@ -2,6 +2,7 @@ import type { ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { buildCallGraph, projectToPairs, type ResourceGraphNode } from "./call-graph.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { readSuppliedResources } from "./resource-input.js";
 
 export interface ResourceNode {
   kind: string;
@@ -67,6 +68,8 @@ export function buildDependencyGraph(
   }
   for (const key of nodes.keys()) if (!deps.has(key)) deps.set(key, new Set());
 
+  addResourceInputEdges(resources, nodes, deps);
+
   // --- Kahn's topological sort ---
   // in-degree[X] = number of X's dependencies (size of deps[X])
   // reverse[dep] = set of nodes that depend on dep (for degree decrement)
@@ -164,3 +167,66 @@ function findCycle(
 
   return [];
 }
+
+/**
+ * Boot-order edges for the one thing a `Telo.Import` does hold: the instances it
+ * hands DOWN to its target library's declared `resources:` inputs.
+ *
+ * An import is otherwise module wiring rather than a runtime node — it is in
+ * `DEPENDENCY_GRAPH_SKIP_KINDS` and the call graph gives it no node at all — but
+ * a borrowed instance must exist before the import initializes, and a cycle
+ * through one is a cycle like any other. The edges are added here rather than
+ * read off the reference field map because the accepted KIND at this slot is
+ * declared by the TARGET library, not by the `Telo.Import` schema, so there is
+ * no `x-telo-ref` for the map to read; the constraint itself is checked by
+ * `validate-resource-inputs`.
+ */
+function addResourceInputEdges(
+  resources: ResourceManifest[],
+  nodes: Map<string, ResourceNode>,
+  deps: Map<string, Set<string>>,
+): void {
+  // Every import that supplies inputs becomes a node FIRST, so a cross-module
+  // reference below can resolve to the import that exports its target.
+  const imports: Array<{ key: string; supplied: Record<string, unknown> }> = [];
+  for (const m of resources) {
+    if (m.kind !== "Telo.Import") continue;
+    const alias = m.metadata?.name as string | undefined;
+    const supplied = readSuppliedResources(m);
+    if (!alias || Object.keys(supplied).length === 0) continue;
+    const key = nodeKey(m.kind, alias);
+    nodes.set(key, { kind: m.kind, name: alias });
+    if (!deps.has(key)) deps.set(key, new Set<string>());
+    imports.push({ key, supplied });
+  }
+  if (imports.length === 0) return;
+
+  const byName = new Map<string, string>();
+  for (const [key, node] of nodes) byName.set(node.name, key);
+  // An import is keyed by its alias, and that is also how a cross-module
+  // reference names it — index those so one resolves.
+  for (const m of resources) {
+    if (m.kind !== "Telo.Import") continue;
+    const alias = m.metadata?.name as string | undefined;
+    const key = alias ? nodeKey(m.kind, alias) : undefined;
+    if (alias && key && nodes.has(key)) byName.set(alias, key);
+  }
+
+  for (const { key, supplied } of imports) {
+    const set = deps.get(key)!;
+    for (const value of Object.values(supplied)) {
+      const ref = value as { name?: unknown; alias?: unknown } | undefined;
+      // A CROSS-MODULE reference (`!ref Other.db`) names an instance exported by
+      // another import, never a local resource. Looking it up in the local name
+      // map would find an unrelated resource of the same name — a wrong edge,
+      // and possibly a phantom cycle — or nothing at all. What it depends on is
+      // the IMPORT that exports it, which is the projection
+      // `localDependencyNames` already makes at runtime.
+      const alias = typeof ref?.alias === "string" ? ref.alias : undefined;
+      const targetName =
+        alias && alias !== "Self" ? alias : typeof ref?.name === "string" ? ref.name : undefined;
+      const target = targetName ? byName.get(targetName) : undefined;
+      if (target && target !== key) set.add(target);
+    }
+  }
+}

package/src/flatten-for-analyzer.ts

@@ -2,6 +2,12 @@ import type { ResourceManifest } from "@telorun/sdk";
 import type { LoadedGraph, LoadedModule } from "./loaded-types.js";
 import type { LoadedFile } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
+import {
+  injectedDeclarations,
+  readLibraryLifecycle,
+  readResourceInputs,
+  type ResourceInput,
+} from "./resource-input.js";
 import type { ZoneModuleDocuments } from "./zone-module-documents.js";
 
 /** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
@@ -414,6 +420,12 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
   // the kernel parses them. A module that declares none is absent, leaving importers ungated
   // (see stampExportedKinds).
   const declaredKinds = new Map<string, readonly string[]>();
+  /** Each library's declared `resources:` block, by module name — the inward
+   *  half, stamped onto its importers below. */
+  const requiredResources = new Map<string, readonly ResourceInput[]>();
+  /** Libraries declaring `lifecycle: shared` — a singleton every import
+   *  resolves to, so a per-import override of it is a contradiction. */
+  const sharedModules = new Set<string>();
   for (const [source, mod] of graph.modules) {
     if (source === graph.rootSource) continue; // root is an Application — no exports
     const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as
@@ -424,6 +436,9 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
     ownerSourceOf.set(moduleName, mod.owner.source);
     specs.push(...reExportSpecsFromExports(moduleName, libDoc.exports?.resources));
     kindModules.push({ module: moduleName, exportsKinds: libDoc.exports?.kinds });
+    const inputs = readResourceInputs(libDoc);
+    if (inputs.length > 0) requiredResources.set(moduleName, inputs);
+    if (readLibraryLifecycle(libDoc) === "shared") sharedModules.add(moduleName);
     if (libDoc.exports?.kinds !== undefined) {
       declaredKinds.set(moduleName, libDoc.exports.kinds.map((e) => parseExportEntry(e).name));
     }
@@ -440,15 +455,100 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
   // Telo.Import manifests so the analyzer can register the re-export mappings.
   const exportedKinds = resolveExportedKinds(kindModules, aliasToModule);
   const imports: Array<{ manifest: ResourceManifest; targetModule: string }> = [];
+  const sources: Array<{ manifest: ResourceManifest; targetSource: string }> = [];
   for (const m of result) {
     if (m.kind !== "Telo.Import") continue;
     const owner = (m.metadata as { source?: string } | undefined)?.source;
     const alias = m.metadata?.name as string | undefined;
-    const target = owner && alias ? graph.importEdges.get(owner)?.get(alias)?.targetModuleName : undefined;
-    if (target) imports.push({ manifest: m, targetModule: target });
+    const edge = owner && alias ? graph.importEdges.get(owner)?.get(alias) : undefined;
+    if (edge?.targetModuleName) imports.push({ manifest: m, targetModule: edge.targetModuleName });
+    if (edge?.targetSource) sources.push({ manifest: m, targetSource: edge.targetSource });
   }
+  stampResolvedSource(sources);
   stampReExportedKinds(imports, exportedKinds);
   stampExportedKinds(imports, declaredKinds);
+  stampRequiredResources(imports, requiredResources, aliasToModule);
+  stampSharedLifecycle(imports, sharedModules);
+}
+
+/** Stamp `metadata.resolvedSource` — the canonical resolved URL of an import's
+ *  target — onto every `Telo.Import`. It is the identity the kernel keys a
+ *  singleton's registry on, so a check that has to decide whether two imports
+ *  reach the SAME library has to key on it too: `resolvedModuleName` is the
+ *  module's own name, which two versions of it share. */
+export function stampResolvedSource(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetSource: string }>,
+): void {
+  for (const { manifest, targetSource } of imports) {
+    (manifest.metadata as Record<string, unknown>).resolvedSource = targetSource;
+  }
+}
+
+/** Stamp `metadata.sharedLibrary` onto every `Telo.Import` whose target declares
+ *  `lifecycle: shared`, so the consumer's pass can reject the per-import
+ *  overrides a singleton has no room for. Stamped on `metadata` for the same
+ *  reason `exportedKinds` is — the `Telo.Import` schema forbids extra top-level
+ *  fields. */
+export function stampSharedLifecycle(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetModule: string }>,
+  shared: ReadonlySet<string>,
+): void {
+  for (const { manifest, targetModule } of imports) {
+    if (!shared.has(targetModule)) continue;
+    (manifest.metadata as Record<string, unknown>).sharedLibrary = true;
+  }
+}
+
+/** Stamp `metadata.requiredResources` — the target library's declared
+ *  `resources:` block, with each kind constraint CANONICALIZED in the library's
+ *  own alias scope — onto every `Telo.Import` whose target declares one.
+ *
+ *  Canonicalized here because this is the only point where the target's own
+ *  import edges are in hand: the consumer's pass sees the flattened list, from
+ *  which the library doc and its alias scope are both gone, so an entry written
+ *  `Sql.Connection` would otherwise be read against whatever the CONSUMER
+ *  happens to alias `Sql` to. Stamped on `metadata` for the same reason
+ *  `exportedKinds` is — the `Telo.Import` schema forbids extra top-level
+ *  fields. An entry whose alias resolves to nothing is stamped with its kind
+ *  unchanged; `validate-resource-inputs.ts` reports that against the library
+ *  that wrote it. */
+export function stampRequiredResources(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetModule: string }>,
+  declared: ReadonlyMap<string, readonly ResourceInput[]>,
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): void {
+  for (const { manifest, targetModule } of imports) {
+    const inputs = declared.get(targetModule);
+    if (!inputs?.length) continue;
+    // A plain name → canonical-kind MAP, deliberately not a list of
+    // `{name, kind}` objects: that shape is character-identical to a resolved
+    // `!ref`, and every reference walk in the analyzer recognises a reference by
+    // exactly those two keys — so the stamp would be read as a malformed
+    // reference sitting in `metadata`.
+    const table: Record<string, string> = {};
+    for (const input of inputs) {
+      table[input.name] = canonicalizeInputKind(input.kind, targetModule, aliasToModule);
+    }
+    (manifest.metadata as Record<string, unknown>).requiredResources = table;
+  }
+}
+
+/** `Alias.Kind` → `<owning module>.Kind` in the DECLARING library's scope.
+ *  `Self.` names the library itself and `Telo.` the kernel built-ins, both of
+ *  which cross no import edge. An unresolvable prefix is returned unchanged. */
+function canonicalizeInputKind(
+  kind: string,
+  ownModule: string,
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): string {
+  const dot = kind.indexOf(".");
+  if (dot <= 0) return kind;
+  const alias = kind.slice(0, dot);
+  const suffix = kind.slice(dot + 1);
+  if (alias === "Self") return `${ownModule}.${suffix}`;
+  if (alias === "Telo") return kind;
+  const module = aliasToModule(ownModule, alias);
+  return module ? `${module}.${suffix}` : kind;
 }
 
 /** Collect every imported library's FULL document set for the zone stage's
@@ -498,7 +598,20 @@ function collectModuleManifests(mod: LoadedModule): ResourceManifest[] {
   for (const p of mod.partials) {
     partials.push(...stampFile(p, ownerModuleName(mod.owner)));
   }
-  return [...owner, ...partials];
+  const all = [...owner, ...partials];
+  // A library's `resources:` block declares the instances it requires from
+  // whoever imports it. Standing a kind-only declaration behind each entry is
+  // what makes `!ref connection` resolve and `resources.connection.<field>` type
+  // in the library's OWN pass — the only pass that sees its internals, since a
+  // consumer's flattened analysis drops the library doc. `selectModuleManifests-
+  // ForAnalysis` drops them again for a non-root module (they are not exported),
+  // and the kernel's import controller filters them out in favour of the
+  // borrowed instance itself.
+  const moduleDoc = all.find((m) => isModuleKind(m.kind));
+  if (moduleDoc) {
+    all.push(...injectedDeclarations(moduleDoc, moduleDoc.metadata?.name as string | undefined));
+  }
+  return all;
 }
 
 function ownerModuleName(file: LoadedFile): string | undefined {

package/src/index.ts

@@ -21,6 +21,9 @@ export {
     selectModuleManifestsForAnalysis,
     stampExportedKinds,
     stampReExportedKinds,
+    stampRequiredResources,
+    stampResolvedSource,
+    stampSharedLifecycle,
     type ParsedExportEntry,
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
@@ -31,9 +34,18 @@ export {
   declaresCelRegion,
   evalPathCovers,
   mergeCelEvalSites,
+  pathMatchesScope,
   NO_CEL_EVAL_SITES,
 } from "./eval-paths.js";
 export type { CelEvalSites } from "./eval-paths.js";
+export {
+  injectedDeclarations,
+  isInjectedDeclaration,
+  readLibraryLifecycle,
+  readResourceInputs,
+  readSuppliedResources,
+} from "./resource-input.js";
+export type { LibraryLifecycle, ResourceInput } from "./resource-input.js";
 export {
   BINDINGS_ANNOTATION,
   bindingContextProperties,

package/src/inline-imports.ts

@@ -54,6 +54,7 @@ export function inlineImportManifests(
       source,
       ...(entry.variables !== undefined ? { variables: entry.variables } : {}),
       ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
+      ...(entry.resources !== undefined ? { resources: entry.resources } : {}),
       ...(entry.runtime !== undefined ? { runtime: entry.runtime } : {}),
       ...(entry.logging !== undefined ? { logging: entry.logging } : {}),
     } as unknown as ResourceManifest;