@telorun/analyzer 0.65.0 → 0.67.0

package/src/analyzer.ts

@@ -20,6 +20,7 @@ import {
   buildCelEnvironment,
   buildImportInputCelEnvironment,
   buildTypedCelEnvironment,
+  isKindDocument,
   type CelHandlers,
 } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
@@ -78,7 +79,7 @@ import {
   type ResourceRuleDiagnostic,
   type ResourceRuleIssue,
 } from "./validate-resource-rules.js";
-import { readResourceRules, type ResourceRule } from "./resource-rule.js";
+import { pointerToPath, readResourceRules, type ResourceRule } from "./resource-rule.js";
 import { readReferrerRules, type ReferrerRule } from "./referrer-rule.js";
 import {
   evaluateReferrerRules,
@@ -87,11 +88,15 @@ import {
   reportUnexercisedReferrerRule,
   validateReferrerRuleDeclarations,
   type Referrer,
+  type ReferrerRuleContext,
   type ReferrerRuleDiagnostic,
   type ReferrerRuleIssue,
 } from "./validate-referrer-rules.js";
+import { analyzerPeerBinder, analyzerPeersTarget } from "./peer-binding.js";
 import {
   describeProjectionFailure,
+  manifestListScope,
+  resolveSchemaProjections,
   type ProjectionFailure,
 } from "./schema-projection.js";
 import {
@@ -118,14 +123,18 @@ import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
   extractAccessChains,
-  extractCelRegionScopes,
   extractContextsFromSchema,
   getManifestItem,
-  pathMatchesScope,
   resolveContextAnnotations,
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
-import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
+import {
+  celEvalModeAt,
+  celEvalSites,
+  mergeCelEvalSites,
+  NO_CEL_EVAL_SITES,
+  type CelEvalSites,
+} from "./eval-paths.js";
 import {
   BINDINGS_ANNOTATION,
   bindingContextProperties,
@@ -148,8 +157,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";
@@ -706,7 +718,7 @@ export class StaticAnalyzer {
    * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
    * apart from a genuine collision, and downstream diagnostic positioning
    * depends on them too. Real callers stamp positions already (the `Loader`,
-   * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+   * `flattenForAnalyzer`, telo studio's `emitDocsFor`, the VSCode
    * extension). Programmatic callers — tests, ad-hoc scripts — should pass
    * their inputs through `withSyntheticPositions(...)` before calling
    * `analyze()`. A missing position throws a clear error rather than
@@ -941,6 +953,11 @@ export class StaticAnalyzer {
     const projectionIssues: SchemaProjectionIssue[] = [];
     const resourceRuleIssues: ResourceRuleIssue[] = [];
     const referrerRuleIssues: ReferrerRuleIssue[] = [];
+    /** Definition docs of the entry's own modules that may declare rules. Their
+     *  referrer-rule declarations are checked after every kind is registered,
+     *  because a `peers:` pointer is checked against the REFERRER kind's schema
+     *  and that kind may be declared later in the same file. */
+    const ownRuleDeclarers: ResourceManifest[] = [];
     // A rule that never had anything to iterate is never proven — the second way
     // coverage varies invisibly, beside the dynamic-leaf skip. Tracked across the
     // whole run and reported once, since "empty on every resource" is not a fact
@@ -998,9 +1015,10 @@ export class StaticAnalyzer {
             effectiveAuthorSchema(m as any, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k)),
           ),
         );
-        referrerRuleIssues.push(
-          ...validateReferrerRuleDeclarations(m as unknown as ResourceManifest),
-        );
+        // Deferred to after the registration loop: the `peers:` half is checked
+        // against the REFERRER kind's schema, and a rule may name a kind
+        // declared later in the same file.
+        ownRuleDeclarers.push(m as unknown as ResourceManifest);
         for (const rule of readReferrerRules((m as Record<string, unknown>).schema)) {
           referrerRuleExercise.set(`${m.metadata?.module}.${m.metadata?.name}#${rule.code}`, {
             manifest: m as unknown as ResourceManifest,
@@ -1056,6 +1074,25 @@ export class StaticAnalyzer {
       defs.register(normalized);
     }
 
+    /**
+     * What a peer rule's `peers:` pointer names in the kind its `referrer:`
+     * filters to.
+     *
+     * Liskov in BOTH directions, which is what the check has to be: the filter
+     * is usually an abstract (`Sql.Schema`, so one rule serves every backend)
+     * while the collection is declared by the backends that implement it, so a
+     * pointer resolving on any candidate resolves the rule. Reported only when
+     * NO candidate declares it, or when every candidate that does holds plain
+     * data — the two shapes where the rule would see no declaration at all.
+     */
+    const peersTarget = analyzerPeersTarget(defs);
+
+    if (!options?.skipValidation) {
+      for (const declarer of ownRuleDeclarers) {
+        referrerRuleIssues.push(...validateReferrerRuleDeclarations(declarer, { peersTarget }));
+      }
+    }
+
     // Reference-form validation — enforce `!ref` as the only reference shape.
     // Runs on the RAW manifests, BEFORE inline extraction and sentinel
     // resolution, while an author-written `{kind, name}` is still
@@ -1498,13 +1535,12 @@ export class StaticAnalyzer {
       return suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles);
     }
 
-    // Build a name→manifest map for looking up referenced resources
-    const byName = new Map<string, ResourceManifest>();
-    for (const m of allManifests) {
-      if (m.metadata?.name) {
-        byName.set(m.metadata.name as string, m);
-      }
-    }
+    // ONE binder for the whole run, built beside the binding it serves: it caches
+    // each referrer's resolved collection, which is what keeps a rule over an
+    // n-entry collection from re-resolving that collection once per entry.
+    const referrerRuleContext: ReferrerRuleContext = {
+      peerBinder: analyzerPeerBinder(defs, aliases, allManifests as ResourceManifest[]),
+    };
 
     // Fail loud on definition schemas AJV cannot compile. `validateAgainstSchema`
     // and `validateWithRefs` swallow compile failures (returning no issues),
@@ -1594,6 +1630,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
@@ -1651,6 +1697,54 @@ export class StaticAnalyzer {
       observedStateContext,
     });
 
+    /**
+     * The schema a resource of this kind is validated against, per DEFINITION.
+     *
+     * Both halves derive a fresh object — `effectiveAuthorSchema` merges along
+     * `extends`, and the closed-schema branch spreads `kind` / `metadata` in —
+     * so asking per resource handed `validateResourceConfig` a schema object it
+     * had never seen. That registry memoizes its compiled AJV validator by
+     * object IDENTITY, precisely because every resource of a kind is checked
+     * against the same one at keystroke time, so a fresh object per resource
+     * recompiled the whole kind schema per resource. Keyed on the definition,
+     * which is stable for the run.
+     */
+    const authorSchemaCache = new WeakMap<object, Record<string, any>>();
+    const validationSchemaFor = (def: ResourceDefinition): Record<string, any> => {
+      const cached = authorSchemaCache.get(def as unknown as object);
+      if (cached) return cached;
+      const authorSchema = effectiveAuthorSchema(def, (k) =>
+        defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+      );
+      // `kind` and `metadata` are implicit on every resource — inject them so
+      // module authors don't have to repeat them under `additionalProperties:
+      // false`.
+      const schema =
+        authorSchema.additionalProperties === false
+          ? {
+              ...authorSchema,
+              properties: {
+                kind: { type: "string" },
+                metadata: { type: "object" },
+                ...authorSchema.properties,
+              },
+            }
+          : authorSchema;
+      authorSchemaCache.set(def as unknown as object, schema);
+      return schema;
+    };
+
+    // One scope for the whole run: it closes over the manifest list and the
+    // registry, neither of which changes per resource, and it is asked once per
+    // schema-valued slot that carries a projection.
+    const resourceProjectionScope = manifestListScope(
+      allManifests as Record<string, any>[],
+      (kind) =>
+        (defs.resolve(kind) ?? defs.resolve(aliases.resolveKind(kind) ?? kind)) as
+          | Record<string, any>
+          | undefined,
+    );
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       const filePath = (m.metadata as { source?: string } | undefined)?.source;
@@ -1681,6 +1775,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
@@ -1749,39 +1852,59 @@ export class StaticAnalyzer {
       }
 
       // Validate resource config against the definition's AUTHOR-FACING schema —
-      // inheritance-resolved: with `base:` the child's own schema (parent config
-      // is internal), else `merge(parent, own)` so a `base:`-less `extends` child
-      // is validated against the inherited fields it may set. For a definition
-      // that neither extends nor uses `base:` this is exactly its own schema.
-      // `kind` and `metadata` are implicit on every resource — inject them so module
-      // authors don't have to repeat them when using additionalProperties: false.
-      const authorSchema = effectiveAuthorSchema(definition, (k) =>
-        defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
-      );
-      if (authorSchema && Object.keys(authorSchema).length > 0) {
-        const schema =
-          authorSchema.additionalProperties === false
-            ? {
-                ...authorSchema,
-                properties: {
-                  kind: { type: "string" },
-                  metadata: { type: "object" },
-                  ...authorSchema.properties,
-                },
-              }
-            : authorSchema;
+      // inheritance-resolved, with `kind` / `metadata` injected. See
+      // `validationSchemaFor`, which is where both derivations and the reason
+      // they are memoized per definition live.
+      const schema = validationSchemaFor(definition);
+      if (Object.keys(schema).length > 0) {
         // Phase 1: collect the pure-CEL leaves and the schema of the slot each
         // flows into. The expression's own type is resolved later, by the
         // engine walk that owns type-checking; this half only knows the target.
         for (const slot of collectCelValueSlots(m, schema, "")) {
           celReturnSlots.push({ manifest: m, resource, filePath, ...slot });
         }
+        // A kind's own schema may point a slot at a PROJECTION — of a resource it
+        // references, or (the empty pointer) of this very declaration, which is
+        // what types a table's seed rows against its own `columns:`. Resolved
+        // PER RESOURCE, because a projection is declaration-derived: the same
+        // kind schema yields a different row shape for every table.
+        //
+        // A failure here is REPORTED, never dropped. An entry that could not be
+        // read vanishes from the projected shape, so the slot typed from it then
+        // rejects a field the author did declare ("'status' is not allowed") with
+        // nothing saying why — the projection's own failure mode, blaming the
+        // wrong line. Entry-module-scoped, like every other schema issue.
+        const projectionFailures: ProjectionFailure[] = [];
+        const projected = resolveSchemaProjections(
+          schema,
+          m as Record<string, any>,
+          resourceProjectionScope,
+          projectionFailures,
+        ) 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",
+              source: SOURCE,
+              message: `${m.kind}/${resource.name}: ${describeProjectionFailure(failure)}`,
+              data: { resource, filePath, path: pointerToPath(failure.pointer) },
+            });
+          }
+        }
         // Phase 2+3: AJV on substituted data — CEL fields replaced with typed
         // placeholders. Through the REGISTRY, so a kind whose schema references
         // a shape declared elsewhere is checked on the instance that holds it.
         const ajvIssues = defs.validateResourceConfig(
-          substituteCelFields(m, schema, undefined, { external: (ref) => defs.schemaForId(ref) }),
-          schema,
+          substituteCelFields(m, projected, undefined, {
+            external: (ref) => defs.schemaForId(ref),
+          }),
+          projected,
         );
         // Phase 4: value slots that must satisfy a type declared elsewhere on
         // the resource (`x-telo-value-schema-from`) — e.g. every row of a
@@ -1816,12 +1939,12 @@ export class StaticAnalyzer {
       for (const report of reportResourceRules(
         m as unknown as ResourceManifest,
         definition as unknown as ResourceManifest,
-        evaluateResourceRules(m as unknown as ResourceManifest, authorSchema),
+        evaluateResourceRules(m as unknown as ResourceManifest, schema),
         !ruleDeclarer || rootModules.has(ruleDeclarer),
       )) {
         diagnostics.push(resourceRuleDiagnostic(report));
       }
-      for (const rule of readResourceRules(authorSchema)) {
+      for (const rule of readResourceRules(schema)) {
         const key = `${definition.metadata?.module}.${definition.metadata?.name}#${rule.code}`;
         const tracked = ruleExercise.get(key);
         if (!tracked) continue;
@@ -1835,7 +1958,7 @@ export class StaticAnalyzer {
       // literal appears on the referring side, where the spelling would be the
       // consumer's import alias rather than anything the rule's author controls.
       // A consumer of the shared call graph, never a second traversal.
-      const referrerRules = readReferrerRules(authorSchema);
+      const referrerRules = readReferrerRules(schema);
       if (referrerRules.length > 0) {
         const referrers = referrersOf(m as unknown as ResourceManifest, getCallGraph());
         for (const report of reportReferrerRules(
@@ -1843,9 +1966,10 @@ export class StaticAnalyzer {
           definition as unknown as ResourceManifest,
           evaluateReferrerRules(
             m as unknown as ResourceManifest,
-            authorSchema,
+            schema,
             referrers,
             kindMatches,
+            referrerRuleContext,
           ),
           !ruleDeclarer || rootModules.has(ruleDeclarer),
         )) {
@@ -1857,13 +1981,25 @@ export class StaticAnalyzer {
             continue;
           }
           diagnostics.push(referrerRuleDiagnostic(report));
+          // A rule that VIOLATED plainly ran, whatever its peer set held. The
+          // unexercised report exists to catch silence — a `peers:` naming
+          // nothing makes every `!peers.exists(…)` pass vacuously — so a finding
+          // is exactly the evidence it asks for.
+          if (report.code === "REFERRER_RULE_VIOLATED") {
+            const violated = referrerRuleExercise.get(
+              `${definition.metadata?.module}.${definition.metadata?.name}#${report.rule}`,
+            );
+            if (violated) violated.exercised = true;
+          }
         }
         for (const rule of referrerRules) {
           const key = `${definition.metadata?.module}.${definition.metadata?.name}#${rule.code}`;
           const tracked = referrerRuleExercise.get(key);
           if (!tracked) continue;
           tracked.seen = true;
-          if (referrerRuleExercised(rule, referrers, kindMatches)) tracked.exercised = true;
+          if (referrerRuleExercised(rule, referrers, kindMatches, referrerRuleContext)) {
+            tracked.exercised = true;
+          }
         }
       }
 
@@ -2065,18 +2201,15 @@ export class StaticAnalyzer {
     // same schema an expression is typed against.
     let celStepContextSchema: Record<string, any> | undefined;
     let celErrorScopes: ReadonlyMap<string, Record<string, any>> = new Map();
-    // Region coverage for the "CEL in a non-eval field" check: the union of
-    // `x-telo-eval` paths (own + capability) and `x-telo-context` /
-    // `x-telo-step-context` / `x-telo-error-context` scopes. A `!cel` outside
-    // every region is read as a literal — the runtime never evaluates it.
-    let celEvalPaths: string[] = [];
+    // Where this kind says its values are evaluated — `x-telo-eval` paths (own +
+    // capability) and the regions covering their contents. A `!cel` outside every
+    // one of them is read as a literal, and one under a compile path resolves at
+    // startup, where observed state cannot exist yet. Both questions are
+    // `celEvalModeAt`, which the editor asks of the same sites.
+    let celSites: CelEvalSites = NO_CEL_EVAL_SITES;
     // The bindings field this kind declares (if any), read by the CEL sites that
     // see the names it introduces.
     let celBindingSites: BindingSites | undefined;
-    // The compile half alone: a field that resolves at startup, where observed
-    // state cannot exist yet.
-    let celCompilePaths: string[] = [];
-    let celRegionScopes: string[] = [];
     let celRuleApplies = false;
 
     visitManifest(
@@ -2231,22 +2364,28 @@ export class StaticAnalyzer {
           celRuleApplies =
             !!e.definition?.schema && capability !== undefined && capability !== "Telo.Template";
           if (celRuleApplies) {
-            const ownSchema = e.definition!.schema as Record<string, any>;
-            const own = buildEvalPaths(ownSchema);
+            // The INHERITANCE-RESOLVED schema, not the kind's own: without
+            // `base:`, an `extends` child is authored against merge(parent, own),
+            // so a CEL-bearing field the parent declares is a legal field on the
+            // child and the kernel expands it — it stamps the merged schema at
+            // definition registration and builds eval paths from that. Reading
+            // the own schema here reported `CEL_IN_NON_EVAL_FIELD` for an
+            // expression the runtime evaluates correctly, which is the two halves
+            // disagreeing about what the manifest means.
+            const ownSchema = effectiveAuthorSchema(
+              e.definition as unknown as ResourceDefinition,
+              (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+            ) as Record<string, any>;
             const capabilityDef = capability ? defs.resolve(capability) : undefined;
-            const parent = capabilityDef?.schema
-              ? buildEvalPaths(capabilityDef.schema as Record<string, any>)
-              : { compile: [], runtime: [] };
-            celEvalPaths = [...own.compile, ...own.runtime, ...parent.compile, ...parent.runtime];
             // A `Telo.Provider`'s fields are implicitly compile-eval — the
             // capability abstract carries the root annotation — so its reads are
             // covered here without the provider restating anything.
-            celCompilePaths = [...own.compile, ...parent.compile];
-            celRegionScopes = extractCelRegionScopes(ownSchema);
+            celSites = mergeCelEvalSites(
+              celEvalSites(ownSchema),
+              celEvalSites(capabilityDef?.schema as Record<string, any> | undefined),
+            );
           } else {
-            celEvalPaths = [];
-            celCompilePaths = [];
-            celRegionScopes = [];
+            celSites = NO_CEL_EVAL_SITES;
           }
         },
         onCel: (e) => {
@@ -2264,8 +2403,7 @@ export class StaticAnalyzer {
             celRuleApplies &&
             engineName === "cel" &&
             celScope.invocationContextSchema === undefined &&
-            !evalPathsCover(celEvalPaths, path) &&
-            !celRegionScopes.some((scope) => pathMatchesScope(path, scope)) &&
+            celEvalModeAt(celSites, path) === null &&
             !pathCrossesNestedResource(m, path)
           ) {
             diagnostics.push({
@@ -2293,7 +2431,7 @@ export class StaticAnalyzer {
                 read.alias ? `${read.alias}.${read.name}` : read.name,
               );
 
-              if (celRuleApplies && evalPathsCover(celCompilePaths, path)) {
+              if (celRuleApplies && celEvalModeAt(celSites, path) === "compile") {
                 diagnostics.push({
                   severity: DiagnosticSeverity.Error,
                   code: "OBSERVED_STATE_IN_STARTUP_FIELD",
@@ -2340,7 +2478,19 @@ export class StaticAnalyzer {
             matchedScope,
           });
 
-          const result = engine.analyze(expr, { celEnv: typedEnv, contextSchema: effectiveContext });
+          const result = engine.analyze(expr, {
+            celEnv: typedEnv,
+            contextSchema: effectiveContext,
+            // `scopeFor` registers every kernel global and every name the site's
+            // context declares, so a root this environment does not know is one
+            // nothing puts in scope. Two places where the CEL belongs to another
+            // scope, both already recognised by the non-eval-field check: a kind
+            // document, whose CEL is written for whoever instantiates the kind,
+            // and anything below a nested inline `{ kind }`, whose CEL the
+            // nested kind evaluates — and which is analyzed again, in its own
+            // scope, as the resource it was extracted into.
+            rootsDeclared: !isKindDocument(m) && !pathCrossesNestedResource(m, path),
+          });
 
           if (result.type !== undefined) {
             let byPath = celTypeByPath.get(m);
@@ -2377,7 +2527,7 @@ export class StaticAnalyzer {
           // intent (a boot timestamp, a run id), so it warns rather than
           // blocking. The engine reports which calls re-evaluate; the eval mode
           // is manifest policy and stays here.
-          if (celRuleApplies && evalPathsCover(celCompilePaths, path)) {
+          if (celRuleApplies && celEvalModeAt(celSites, path) === "compile") {
             const volatile = [
               ...new Set(result.calls.filter((c) => c.deterministic === false).map((c) => c.name)),
             ].sort();
@@ -2433,7 +2583,7 @@ export class StaticAnalyzer {
           }
         },
       },
-      { aliases },
+      { aliases, aliasesByModule, rootModules },
     );
 
     // The two halves of "does this expression fit the slot it flows into" meet
@@ -2522,6 +2672,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" },