@telorun/analyzer 0.66.0 → 0.68.0

package/dist/validate-sensitive-slots.js

@@ -0,0 +1,75 @@
+import { SCHEMA_REGION_KEYS } from "./schema-region.js";
+const ANNOTATION = "x-telo-sensitive";
+/** The only regions the kernel reads the annotation from. */
+const CONTRACT_KEYS = new Set(["inputType", "outputType"]);
+export function validateSensitiveSlots(manifest) {
+    const issues = [];
+    const walk = (node, path, seen) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            node.forEach((child, i) => walk(child, [...path, i], seen));
+            return;
+        }
+        const record = node;
+        if (Object.hasOwn(record, ANNOTATION)) {
+            const dotted = path.join(".");
+            if (record[ANNOTATION] !== true) {
+                issues.push({
+                    code: "SENSITIVE_ANNOTATION_INVALID",
+                    manifest,
+                    path: dotted,
+                    message: `'${ANNOTATION}' must be \`true\`; got ${JSON.stringify(record[ANNOTATION])}. ` +
+                        `It is a marker, not a level — a value other than \`true\` reads as "not sensitive".`,
+                });
+            }
+            else {
+                const region = enclosingSchemaRegion(path);
+                if (region === undefined || !CONTRACT_KEYS.has(region)) {
+                    issues.push({
+                        code: "SENSITIVE_ANNOTATION_MISPLACED",
+                        manifest,
+                        path: dotted,
+                        message: `'${ANNOTATION}' is only read from a resource's declared contract ` +
+                            `(\`inputType\` / \`outputType\`), and this node is ` +
+                            (region === undefined
+                                ? "not inside a schema at all"
+                                : `inside \`${region}\``) +
+                            `. The kernel will not redact it, so the value would still reach trace ` +
+                            `payloads and the debug wire. Move the mark onto the contract property ` +
+                            `that carries the value.`,
+                    });
+                }
+            }
+        }
+        for (const [key, child] of Object.entries(record)) {
+            walk(child, [...path, key], seen);
+        }
+    };
+    walk(manifest, [], new Set());
+    return issues;
+}
+/**
+ * The OUTERMOST segment naming a schema-valued key, or `undefined` when the node
+ * is not inside a schema.
+ *
+ * Outermost, not nearest, because a contract is routinely written in the inline
+ * `{kind: Telo.JsonSchema, schema: …}` form — so the path to a marked property is
+ * `outputType.schema.properties.headers`, and the nearest region key is that
+ * wrapper's own `schema`. Reading it as a kind's configuration would report every
+ * correctly-marked contract as misplaced, which is how this check first behaved.
+ *
+ * It is the same reasoning `expandManifestFragments` uses when it keys on the
+ * top-level slot: the object a contract resolver is handed is the one under
+ * `inputType` / `outputType`, whatever nesting the authoring form adds beneath.
+ */
+function enclosingSchemaRegion(path) {
+    for (const segment of path) {
+        if (typeof segment === "string" && SCHEMA_REGION_KEYS.includes(segment))
+            return segment;
+    }
+    return undefined;
+}

package/dist/validate-template-dispatch.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * A `!ref` at a definition's dispatch slot must name a sibling `resources:`
+ * entry.
+ *
+ * `!ref` is the one spelling an author — and the editor's rename, completion and
+ * go-to-definition — expects to be RESOLVED. But a `Telo.Definition` is in both
+ * `REF_VALIDATION_SKIP_KINDS` and `REF_RESOLUTION_SKIP_KINDS`, and the dispatch
+ * slots carry no `x-telo-ref` (the accepted targets are the definition's own
+ * template-internal entries, not resources of any module), so no reference pass
+ * reaches them. Introducing the tag at a slot nothing resolves would be worse
+ * than the string form it replaces: a typo that used to be an obvious runtime
+ * miss becomes a typo in a construct that advertises static resolution.
+ *
+ * Decidable only when every sibling name is LITERAL. A template routinely names
+ * its entries with CEL (`name: !cel "self.name + '-query'"`), and an expression
+ * could expand to the referenced name — so one dynamic sibling switches the
+ * check off for that definition rather than inventing a miss.
+ *
+ * Entry-module-scoped, like every other declaration check: a published
+ * dependency's template body is not the consumer's to fix.
+ *
+ * Browser-safe.
+ */
+export declare function validateTemplateDispatch(manifests: ResourceManifest[], rootModules: ReadonlySet<string>): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-template-dispatch.d.ts.map

package/dist/validate-template-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-template-dispatch.d.ts","sourceRoot":"","sources":["../src/validate-template-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AASzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,kBAAkB,EAAE,CAgDtB"}

package/dist/validate-template-dispatch.js

@@ -0,0 +1,95 @@
+import { isRefSentinel } from "@telorun/templating";
+import { distance } from "./levenshtein.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/** The four slots a `Telo.Definition` names its dispatch target in. Each takes
+ *  the same grammar; which one is legal for a given capability is
+ *  `validate-provider-coherence`'s question, not this one's. */
+const DISPATCH_FIELDS = ["invoke", "run", "provide", "mount"];
+/**
+ * A `!ref` at a definition's dispatch slot must name a sibling `resources:`
+ * entry.
+ *
+ * `!ref` is the one spelling an author — and the editor's rename, completion and
+ * go-to-definition — expects to be RESOLVED. But a `Telo.Definition` is in both
+ * `REF_VALIDATION_SKIP_KINDS` and `REF_RESOLUTION_SKIP_KINDS`, and the dispatch
+ * slots carry no `x-telo-ref` (the accepted targets are the definition's own
+ * template-internal entries, not resources of any module), so no reference pass
+ * reaches them. Introducing the tag at a slot nothing resolves would be worse
+ * than the string form it replaces: a typo that used to be an obvious runtime
+ * miss becomes a typo in a construct that advertises static resolution.
+ *
+ * Decidable only when every sibling name is LITERAL. A template routinely names
+ * its entries with CEL (`name: !cel "self.name + '-query'"`), and an expression
+ * could expand to the referenced name — so one dynamic sibling switches the
+ * check off for that definition rather than inventing a miss.
+ *
+ * Entry-module-scoped, like every other declaration check: a published
+ * dependency's template body is not the consumer's to fix.
+ *
+ * Browser-safe.
+ */
+export function validateTemplateDispatch(manifests, rootModules) {
+    const out = [];
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const meta = m.metadata;
+        const name = meta?.name;
+        if (!name)
+            continue;
+        if (meta?.module && !rootModules.has(meta.module))
+            continue;
+        const bodies = m.resources;
+        if (!Array.isArray(bodies))
+            continue;
+        const siblings = [];
+        let anyDynamic = false;
+        for (const entry of bodies) {
+            const entryName = entry?.metadata?.name;
+            if (typeof entryName === "string" && !entryName.includes("${{"))
+                siblings.push(entryName);
+            else if (entryName !== undefined)
+                anyDynamic = true;
+        }
+        if (anyDynamic)
+            continue;
+        for (const field of DISPATCH_FIELDS) {
+            const value = m[field];
+            if (!isRefSentinel(value))
+                continue;
+            const source = value.source;
+            const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
+            if (siblings.includes(target))
+                continue;
+            const suggestion = nearest(target, siblings);
+            out.push({
+                severity: DiagnosticSeverity.Error,
+                code: "TEMPLATE_DISPATCH_UNKNOWN",
+                source: SOURCE,
+                message: `${m.kind}/${name}: '${field}: !ref ${source}' names no entry in 'resources:'. ` +
+                    `Available: ${siblings.join(", ") || "(none)"}.` +
+                    (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+                data: {
+                    resource: { kind: m.kind, name },
+                    filePath: meta?.source,
+                    path: field,
+                    ...(suggestion ? { fix: { replacement: suggestion } } : {}),
+                },
+            });
+        }
+    }
+    return out;
+}
+/** The closest sibling name, when one is close enough to be a typo rather than a
+ *  different name. */
+function nearest(target, candidates) {
+    let best;
+    for (const candidate of candidates) {
+        const d = distance(target, candidate);
+        if (!best || d < best.d)
+            best = { name: candidate, d };
+    }
+    const limit = Math.max(1, Math.floor(target.length / 3));
+    return best && best.d <= limit ? best.name : undefined;
+}

package/dist/value-type-keyword.d.ts

@@ -28,7 +28,7 @@ import type { KeywordDefinition } from "ajv";
  *
  * `x-telo-type` is deliberately absent — it is the one that emits code.
  */
-export declare const ANNOTATION_KEYWORDS: readonly ["x-telo-bindings-from", "x-telo-catches-for", "x-telo-context", "x-telo-context-collection-from", "x-telo-context-element-from", "x-telo-context-from", "x-telo-context-from-ref-kind", "x-telo-context-from-root", "x-telo-context-ref-from", "x-telo-error-context", "x-telo-eval", "x-telo-inline", "x-telo-outcome-list", "x-telo-provides-zone", "x-telo-ref", "x-telo-requires-zone", "x-telo-resource-rules", "x-telo-schema-from", "x-telo-schema-map", "x-telo-schema-projection", "x-telo-schema-projection-from", "x-telo-scope", "x-telo-step-context", "x-telo-topology-role", "x-telo-value-schema-from", "x-telo-widget"];
+export declare const ANNOTATION_KEYWORDS: readonly ["x-telo-bindings-from", "x-telo-catches-for", "x-telo-context", "x-telo-context-collection-from", "x-telo-context-element-from", "x-telo-context-from", "x-telo-context-from-ref-kind", "x-telo-context-from-root", "x-telo-context-ref-from", "x-telo-error-context", "x-telo-eval", "x-telo-inline", "x-telo-outcome-list", "x-telo-provides-zone", "x-telo-ref", "x-telo-requires-zone", "x-telo-resource-rules", "x-telo-schema-from", "x-telo-schema-map", "x-telo-schema-projection", "x-telo-schema-projection-from", "x-telo-scope", "x-telo-sensitive", "x-telo-step-context", "x-telo-topology-role", "x-telo-value-schema-from", "x-telo-widget"];
 /**
  * The `x-telo-type` keyword.
  *

package/dist/value-type-keyword.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,onBA2BtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}
+{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,woBA4BtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}

package/dist/value-type-keyword.js

@@ -54,6 +54,7 @@ export const ANNOTATION_KEYWORDS = [
     "x-telo-schema-projection",
     "x-telo-schema-projection-from",
     "x-telo-scope",
+    "x-telo-sensitive",
     "x-telo-step-context",
     "x-telo-topology-role",
     "x-telo-value-schema-from",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,13 +43,13 @@
     "jsonpath-plus": "^10.3.0",
     "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.17.0"
+    "@telorun/templating": "0.18.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.82.1"
+    "@telorun/sdk": "0.83.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analyzer.ts

@@ -108,6 +108,10 @@ import {
   validateValueTypeSlots,
   type ValueTypeSlotIssue,
 } from "./validate-value-type-slots.js";
+import {
+  validateSensitiveSlots,
+  type SensitiveSlotIssue,
+} from "./validate-sensitive-slots.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
@@ -157,8 +161,11 @@ import { validateInvocationContract } from "./validate-invocation-contract.js";
 import { collectRefInputIssues, collectStepInputIssues } from "./validate-step-inputs.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
-import { validateReferences } from "./validate-references.js";
+import { kindSatisfies, validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
+import { isInjectedDeclaration } from "./resource-input.js";
+import { validateResourceInputs } from "./validate-resource-inputs.js";
+import { validateTemplateDispatch } from "./validate-template-dispatch.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 import { readStepSlot } from "./step-slot.js";
@@ -976,10 +983,16 @@ export class StaticAnalyzer {
     // definition's `schema:` does. Same scoping as every other schema issue —
     // the entry's own modules, since a dependency is not the consumer's to fix.
     const valueTypeSlotIssues: ValueTypeSlotIssue[] = [];
+    // `x-telo-sensitive` rides the same walk and the same scoping. It is read by
+    // ONE consumer — the kernel, off a bound contract — so an occurrence outside
+    // `inputType` / `outputType` is inert; for a security control, inert-and-
+    // silent is the failure worth reporting.
+    const sensitiveSlotIssues: SensitiveSlotIssue[] = [];
     for (const m of manifests) {
       const declaringModule = (m.metadata as { module?: string } | undefined)?.module;
       if (!declaringModule || rootModules.has(declaringModule)) {
         valueTypeSlotIssues.push(...validateValueTypeSlots(m as unknown as ResourceManifest));
+        sensitiveSlotIssues.push(...validateSensitiveSlots(m as unknown as ResourceManifest));
       }
     }
     for (const m of manifests) {
@@ -1209,6 +1222,22 @@ export class StaticAnalyzer {
           },
         });
       }
+      for (const issue of sensitiveSlotIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+          },
+        });
+      }
       // Same split for the two zone annotations. Unreadable ones fail in
       // OPPOSITE directions — a dropped requirement is silently unenforced, a
       // dropped provision invents failures — so neither can be left to
@@ -1627,6 +1656,16 @@ export class StaticAnalyzer {
     const runReachable = reportsObservedState
       ? collectRunReachableNames(getCallGraph())
       : new Set<string>();
+    // "Nothing starts this" is DECLARATION-derived, and a library does not
+    // declare its injected inputs — whether the application starts the instance
+    // it hands down is answerable only where that instance is declared. Inside
+    // the library the question has no answer, so the name is treated as
+    // reachable rather than reported on a `targets:` list the author cannot
+    // write. The check still runs at the injection site, against the real
+    // declaration.
+    for (const m of allManifests) {
+      if (isInjectedDeclaration(m)) runReachable.add(m.metadata?.name as string);
+    }
 
     // Build typed kernel globals schema so x-telo-context chain validation
     // recognises variables, secrets, resources, env automatically
@@ -1762,6 +1801,15 @@ export class StaticAnalyzer {
         continue;
       }
 
+      // A kind-only stand-in for a `resources:` entry is a DECLARATION, not an
+      // instantiation: its kind is routinely an abstract and its configuration
+      // is the importer's to supply, so validating it here would report a
+      // non-instantiable kind and a page of missing required fields against a
+      // block that is correct. Its kind is checked where it was written, by
+      // `validate-resource-inputs`; it participates here only as a resolution
+      // target and as a CEL type.
+      if (isInjectedDeclaration(m)) continue;
+
       const resource = { kind: m.kind, name: m.metadata?.name as string };
 
       // Resolve kind through alias if needed; direct lookup takes priority so that
@@ -1861,6 +1909,11 @@ export class StaticAnalyzer {
         ) as Record<string, any>;
         if (!ownModule || rootModules.has(ownModule)) {
           for (const failure of projectionFailures) {
+            // A projection through a library's own resource INPUT is
+            // unanswerable here — the entries belong to the declaration the
+            // importer supplies — so it is not a defect in the block that named
+            // it. The check runs at the injection site instead.
+            if (failure.reason === "injected") continue;
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
               code: "SCHEMA_PROJECTION_FROM_UNRESOLVED",
@@ -2556,7 +2609,7 @@ export class StaticAnalyzer {
           }
         },
       },
-      { aliases },
+      { aliases, aliasesByModule, rootModules },
     );
 
     // The two halves of "does this expression fit the slot it flows into" meet
@@ -2645,6 +2698,22 @@ export class StaticAnalyzer {
     // Warn about declared variables / secrets / ports that no CEL references.
     diagnostics.push(...validateUnusedDeclarations(allManifests, this.celEnv));
 
+    // A `!ref` at a definition's dispatch slot must name a sibling `resources:`
+    // entry — the slot no reference pass reaches, so the tag would otherwise
+    // advertise a resolution nothing performs.
+    diagnostics.push(...validateTemplateDispatch(allManifests, rootModules));
+
+    // A library's declared resource inputs, and every import that supplies them.
+    diagnostics.push(
+      ...validateResourceInputs(
+        allManifests,
+        defs,
+        aliases,
+        rootModules,
+        (supplied, required) => kindSatisfies(supplied, required, defs),
+      ),
+    );
+
     // Reroute diagnostics on synthetic (inline-extracted) resources back to
     // the chain root so position-index lookups land on the parent doc.
     return rewriteSyntheticOrigins(

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" },