@telorun/analyzer 0.66.0 → 0.68.0

package/src/validate-identifier-names.ts

@@ -9,6 +9,7 @@ import {
   type NameLevel,
   type NameViolation,
 } from "./identifier-name.js";
+import { isInjectedDeclaration } from "./resource-input.js";
 import { type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -56,6 +57,11 @@ export function validateIdentifierNames(
     // would blame them for a spelling this pass's own pipeline chose.
     if (metadata?.xTeloOrigin) continue;
 
+    // A kind-only stand-in for a `resources:` entry carries the name the author
+    // wrote in that block, and the block's own keys are checked below — on the
+    // module doc, where the name is written and a squiggle can land.
+    if (isInjectedDeclaration(manifest)) continue;
+
     const ownModule = metadata?.module as string | undefined;
     if (ownModule && !rootModules.has(ownModule)) continue;
 
@@ -74,7 +80,10 @@ export function validateIdentifierNames(
     // keys are the imported library's declarations, so a violation there is
     // the library author's, reported when their module is analyzed as a root.
     if (manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library") {
-      for (const field of ["variables", "secrets", "ports"] as const) {
+      // `resources:` joins them: a library's resource inputs are named in the
+      // same identifier space (`!ref connection`, `resources.connection`) and
+      // break the same way.
+      for (const field of ["variables", "secrets", "ports", "resources"] as const) {
         const block = (manifest as Record<string, unknown>)[field];
         if (!block || typeof block !== "object" || Array.isArray(block)) continue;
         for (const key of Object.keys(block as Record<string, unknown>)) {
@@ -149,8 +158,14 @@ function surfaceFor(kind: string): string {
   }
 }
 
-function singular(field: "variables" | "secrets" | "ports"): string {
-  return field === "variables" ? "variable" : field === "secrets" ? "secret" : "port";
+function singular(field: "variables" | "secrets" | "ports" | "resources"): string {
+  return field === "variables"
+    ? "variable"
+    : field === "secrets"
+      ? "secret"
+      : field === "ports"
+        ? "port"
+        : "resource input";
 }
 
 function push(

package/src/validate-references.ts

@@ -18,11 +18,53 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 const SOURCE = "telo-analyzer";
 
 /**
- * Checks whether `kind` satisfies the ref constraint in `entry`.
- * Returns an empty array when valid, or mismatch error strings when not.
- * Returns an empty array immediately when the ref identity is not registered
- * (partial context — skip check rather than false-positive).
+ * Liskov substitutability at a kind constraint: is `resolved` (a canonical
+ * `<module>.<Kind>`) accepted where `targetKind` is required?
+ *
+ * THE one implementation — `checkKind` below builds a MESSAGE from it and adds
+ * nothing to the rule, so a resource input's injection site and an ordinary ref
+ * slot cannot come to disagree about what satisfies a constraint.
+ *
+ * A value satisfies the slot when it transitively extends the target kind, or —
+ * for a CONCRETE target — IS that kind; `getByExtends` is the same transitive
+ * subtype index for both, and an abstract is satisfied only by an implementer,
+ * never by the abstract itself (which is non-instantiable). Accepts a constraint
+ * that resolves to nothing, and an abstract with no loaded implementations:
+ * partial context, where a rejection would be a guess.
  */
+export function kindSatisfies(
+  resolved: string,
+  targetKind: string,
+  registry: DefinitionRegistry,
+): boolean {
+  const canonical = registry.resolveRef(targetKind) ?? targetKind;
+  const targetDef = registry.resolve(canonical);
+  if (!targetDef) return true;
+  if (targetDef.kind !== "Telo.Abstract" && resolved === canonical) return true;
+  const subtypes = registry.getByExtends(canonical);
+  if (subtypes.some((d) => `${d.metadata.module}.${d.metadata.name}` === resolved)) return true;
+  // Leniency is about the CANDIDATE, not about the population, and it is the
+  // same question for an abstract target and a concrete one. Accepting whenever
+  // no subtype happened to be loaded silenced the check exactly where it was
+  // needed: an app whose imports declare no `Telo.Runnable` is an app whose boot
+  // targets are all wrong, and every one of them passed.
+  //
+  // An UNREGISTERED candidate is not partial context, and the distinction is
+  // load-bearing: a kind nobody declared is an unknown kind or an unimported
+  // alias prefix (`NotAnAlias.Script`), which is precisely what this check
+  // exists to report. Only a kind that IS declared, whose ancestry reaches
+  // something this analysis never saw, is undecidable — there the missing hop is
+  // where the target it appears not to reach could have been declared.
+  // A candidate the registry never saw cannot be judged on what it implements —
+  // the analysis simply does not hold it. Whether its NAME is resolvable is a
+  // different question, asked of the alias scope by the caller.
+  if (!registry.resolve(resolved)) return true;
+  return !registry.ancestryResolved(resolved);
+}
+
+/** {@link kindSatisfies} at every kind a slot accepts, rendered as messages.
+ *  The acceptance rule is not restated here — only what to say when it fails,
+ *  which needs the slot's alternatives and the target's flavour. */
 function checkKind(
   kind: string,
   entry: RefFieldEntry,
@@ -30,23 +72,30 @@ function checkKind(
   aliases: AliasResolver,
 ): string[] {
   const resolved = aliases.resolveKind(kind) ?? kind;
+  // A qualified kind whose prefix names no import in this scope is a bad NAME
+  // rather than a bad type — `{kind: NotAnAlias.Script}` where only `Lib` is
+  // imported — and this check is the only place it surfaces, so it is never
+  // waved through as partial context. Asked of the resolver, which reports
+  // `unknown` for exactly that case: a kind reached through a DECLARED alias
+  // resolves (`ok`) even when the target's definitions are not loaded, and a
+  // gated one says so separately.
+  const unknownAlias =
+    kind.includes(".") &&
+    aliases.resolveKindResult(kind).status === "unknown" &&
+    // …and the registry does not hold it under the name as written either. A
+    // manifest may carry a canonical `<module>.<Kind>`, which no alias resolves
+    // and which is nonetheless perfectly identified.
+    registry.resolve(resolved) === undefined;
   const errors: string[] = [];
   for (const refStr of entry.refs) {
     const targetKind = registry.resolveRef(refStr);
     if (!targetKind) return [];
     const targetDef = registry.resolve(targetKind);
     if (!targetDef) return [];
-    // Liskov substitutability: a value satisfies the slot when it transitively
-    // extends the target kind, or — for a CONCRETE target — IS that kind.
-    // `getByExtends` is the same transitive subtype index for abstract and
-    // concrete targets alike; an abstract is satisfied only by an implementer,
-    // never by the abstract kind itself (which is non-instantiable).
-    if (targetDef.kind !== "Telo.Abstract" && resolved === targetKind) return [];
+    if (!unknownAlias && kindSatisfies(resolved, targetKind, registry)) return [];
     const subtypes = registry.getByExtends(targetKind);
     const subtypeKinds = new Set(subtypes.map((d) => `${d.metadata.module}.${d.metadata.name}`));
-    if (subtypeKinds.has(resolved)) return [];
     if (targetDef.kind === "Telo.Abstract") {
-      if (subtypes.length === 0) return []; // partial context — no implementations loaded yet
       // Suggest only what an author can actually wire: with abstract-extends-
       // abstract real (Telo.Executable over Invocable/Runnable), the transitive
       // subtype list contains abstracts, which are non-instantiable and would
@@ -54,9 +103,16 @@ function checkKind(
       const concrete = subtypes
         .filter((d) => d.kind !== "Telo.Abstract")
         .map((d) => `${d.metadata.module}.${d.metadata.name}`);
-      const options = (concrete.length > 0 ? concrete : [...subtypeKinds]).join(", ");
+      const options = concrete.length > 0 ? concrete : [...subtypeKinds];
+      // With nothing loaded that implements the target there is no list to
+      // offer, so the message says what this kind IS instead — which is the
+      // half the author can act on ("it declares 'Telo.Invocable'" points
+      // straight at a boot target that should have been an invoke step).
+      const declared = registry.resolve(resolved)?.capability;
       errors.push(
-        `'${kind}' does not implement '${targetKind}' (known implementations: ${options})`,
+        options.length > 0
+          ? `'${kind}' does not implement '${targetKind}' (known implementations: ${options.join(", ")})`
+          : `'${kind}' does not implement '${targetKind}'${declared ? ` — it declares '${declared}'` : ""}`,
       );
     } else {
       const options = subtypeKinds.size > 0 ? ` or a subtype (${[...subtypeKinds].join(", ")})` : "";

package/src/validate-resource-inputs.ts

@@ -0,0 +1,367 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { findDynamicLeaf } from "./resource-rule.js";
+import { readResourceInputs, readSuppliedResources } from "./resource-input.js";
+import { type AnalysisDiagnostic, DiagnosticSeverity } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** A target library's declared `resources:` block, canonicalized in that
+ *  library's own alias scope and stamped onto the `Telo.Import` by
+ *  `stampRequiredResources`: entry name → canonical kind. */
+type RequiredResources = Record<string, string>;
+
+/**
+ * The strict half of {@link readResourceInputs} — the `validate-ref-slots.ts`
+ * split applied to the resource-input boundary, and not optional for the same
+ * reason: the two sides fail in OPPOSITE directions. An unreadable DECLARATION
+ * leaves the library referencing a name nothing stands behind; an unchecked
+ * INJECTION hands a library an instance of a kind it never asked for, which
+ * surfaces as a method-missing failure inside someone else's module.
+ *
+ * Two surfaces, scoped the same way every other declaration check is — to the
+ * entry's own modules, since a published dependency's block is not the
+ * consumer's to fix:
+ *
+ *  - **The library's own declaration.** Each entry's alias-qualified `kind:` must
+ *    resolve in the DECLARING module's scope (`RESOURCE_INPUT_KIND_UNRESOLVED`).
+ *    A constraint that resolves to nothing accepts anything, which is the same
+ *    hole `X_TELO_REF_UNRESOLVED` exists to close one level down.
+ *  - **The injection site.** Every declared entry must be supplied
+ *    (`RESOURCE_INPUT_MISSING` — the same failure as a missing required
+ *    variable), nothing beyond them may be (`RESOURCE_INPUT_UNKNOWN`), the value
+ *    must name a resource that exists (`RESOURCE_INPUT_UNRESOLVED`), and its
+ *    kind must satisfy the declared constraint transitively
+ *    (`RESOURCE_INPUT_KIND_MISMATCH`).
+ *
+ * Browser-safe.
+ */
+export function validateResourceInputs(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  rootModules: Set<string>,
+  /** Kind acceptance, transitively — the `checkKind` rule `validate-references`
+   *  applies at an ordinary ref slot, passed in rather than re-derived so the
+   *  two cannot disagree about what satisfies a constraint. */
+  acceptsKind: (suppliedKind: string, requiredKind: string) => boolean,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  const isOwn = (module: string | undefined): boolean => !module || rootModules.has(module);
+
+  // --- the library's own declaration -------------------------------------
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Library") continue;
+    const moduleName = m.metadata?.name as string | undefined;
+    // Only the entry's own modules, so the declaring scope is always the root
+    // alias table — a library analyzed here IS a root module.
+    if (!isOwn(moduleName)) continue;
+    const scope = aliases;
+    const exported = new Set(
+      (((m as Record<string, any>).exports?.resources ?? []) as unknown[]).filter(
+        (e): e is string => typeof e === "string",
+      ),
+    );
+    for (const input of readResourceInputs(m)) {
+      // An input is the IMPORTER's instance, borrowed. Exporting it back out
+      // would forward a kind-only stand-in into the consumer's flattened set as
+      // a resource this library declares — a phantom the consumer can `!ref`
+      // and whose kind constraint is all there is behind it. Handing an
+      // instance straight back to whoever supplied it is also a relation
+      // nothing needs; if it ever does, it should be a decision rather than a
+      // name collision nobody noticed.
+      if (exported.has(input.name)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_EXPORTED",
+          source: SOURCE,
+          message:
+            `Resource input '${input.name}' is also listed in 'exports.resources'. An input is ` +
+            `an instance the importer supplies, not one this library declares, so there is ` +
+            `nothing to export — remove it from 'exports.resources', or rename the input.`,
+          data: {
+            resource: { kind: m.kind, name: moduleName as string },
+            filePath: (m.metadata as { source?: string } | undefined)?.source,
+            path: `resources.${input.name}`,
+          },
+        });
+      }
+      if (registry.resolve(input.kind) ?? registry.resolve(scope.resolveKind(input.kind) ?? "")) {
+        continue;
+      }
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "RESOURCE_INPUT_KIND_UNRESOLVED",
+        source: SOURCE,
+        message:
+          `Resource input '${input.name}' is constrained to kind '${input.kind}', which does not ` +
+          `resolve in this library's scope. Write it alias-qualified — '<Alias>.<Kind>' for an ` +
+          `import declared in this file, 'Self.<Kind>' for a kind this library owns, or ` +
+          `'Telo.<Kind>' for a built-in. An unresolvable constraint accepts anything.`,
+        data: {
+          resource: { kind: m.kind, name: moduleName as string },
+          filePath: (m.metadata as { source?: string } | undefined)?.source,
+          path: `resources.${input.name}.kind`,
+        },
+      });
+    }
+  }
+
+  // --- the injection site --------------------------------------------------
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const meta = m.metadata as
+      | {
+          name?: string;
+          module?: string;
+          source?: string;
+          resolvedModuleName?: string;
+          requiredResources?: RequiredResources;
+          sharedLibrary?: boolean;
+          resolvedSource?: string;
+        }
+      | undefined;
+    const alias = meta?.name;
+    if (!alias || !isOwn(meta?.module)) continue;
+    // An import whose target identity was never established registers nothing —
+    // reporting a missing input against it would blame the author for a
+    // dependency the loader has already said it could not obtain.
+    if (!meta?.resolvedModuleName) continue;
+
+    // A singleton has no room for a per-import override: `logging:` scopes a
+    // subtree that is no longer this import's subtree, and `runtime:` selects a
+    // controller backend for a library that is instantiated once. Whichever
+    // import happened to be created first would decide, so the field is
+    // rejected rather than silently applied to everyone or silently dropped.
+    if (meta.sharedLibrary === true) {
+      for (const field of ["logging", "runtime"] as const) {
+        if ((m as Record<string, unknown>)[field] === undefined) continue;
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "SHARED_LIBRARY_OVERRIDE",
+          source: SOURCE,
+          message:
+            `Import '${alias}' declares '${field}:', but module ` +
+            `'${meta.resolvedModuleName}' is 'lifecycle: shared' — one instantiation for the ` +
+            `whole application, so a per-import override cannot apply to it. Remove it, or ` +
+            `make the library 'lifecycle: isolated'.`,
+          data: {
+            resource: { kind: m.kind, name: alias },
+            filePath: meta.source,
+            path: field,
+          },
+        });
+      }
+    }
+
+    const required = Object.entries(meta.requiredResources ?? {});
+    const supplied = readSuppliedResources(m);
+    const declared = new Map(required);
+    const resource = { kind: m.kind, name: alias };
+    const filePath = meta.source;
+
+    for (const [entryName, entryKind] of required) {
+      if (entryName in supplied) continue;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "RESOURCE_INPUT_MISSING",
+        source: SOURCE,
+        message:
+          `Import '${alias}' does not supply the resource input '${entryName}', which module ` +
+          `'${meta.resolvedModuleName}' requires (kind '${entryKind}'). Add ` +
+          `\`resources: { ${entryName}: !ref <name> }\` to the import.`,
+        data: { resource, filePath, path: "resources" },
+      });
+    }
+
+    for (const [name, value] of Object.entries(supplied)) {
+      const path = `resources.${name}`;
+      const entry = declared.get(name);
+      if (!entry) {
+        const known = required.map(([n]) => n).join(", ") || "(none)";
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_UNKNOWN",
+          source: SOURCE,
+          message:
+            `Import '${alias}' supplies a resource input '${name}', which module ` +
+            `'${meta.resolvedModuleName}' does not declare. Declared inputs: ${known}.`,
+          data: { resource, filePath, path },
+        });
+        continue;
+      }
+      // Phase 2.5 rewrote a resolvable `!ref` to `{kind, name}`; a sentinel that
+      // survived names nothing the importer can reach.
+      if (isRefSentinel(value)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_UNRESOLVED",
+          source: SOURCE,
+          message: `Import '${alias}': resource input '${name}' → resource '${value.source}' not found`,
+          data: { resource, filePath, path },
+        });
+        continue;
+      }
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_UNRESOLVED",
+          source: SOURCE,
+          message:
+            `Import '${alias}': resource input '${name}' must be a '!ref' to a resource this ` +
+            `module declares.`,
+          data: { resource, filePath, path },
+        });
+        continue;
+      }
+      const suppliedKind = (value as { kind?: unknown }).kind;
+      if (typeof suppliedKind !== "string") continue;
+      const canonical = aliases.resolveKind(suppliedKind) ?? suppliedKind;
+      if (acceptsKind(canonical, entry)) continue;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "RESOURCE_INPUT_KIND_MISMATCH",
+        source: SOURCE,
+        message:
+          `Import '${alias}': resource input '${name}' is '${suppliedKind}' (resolved: ` +
+          `'${canonical}'), which does not satisfy the declared constraint '${entry}'.`,
+        data: { resource, filePath, path },
+      });
+    }
+  }
+
+  out.push(...sharedLibraryConflicts(manifests, isOwn));
+
+  return out;
+}
+
+/** One import's supplied configuration, as the conflict check compares it. */
+interface SuppliedConfig {
+  readonly alias: string;
+  readonly module: string | undefined;
+  readonly filePath: string | undefined;
+  readonly blocks: ReadonlyMap<string, Record<string, unknown>>;
+}
+
+const SUPPLIED_BLOCKS = ["variables", "secrets", "resources"] as const;
+
+/**
+ * Two imports of ONE `lifecycle: shared` library supplying different values.
+ *
+ * The runtime half (`ERR_SHARED_LIBRARY_CONFLICT`) is authoritative — it holds
+ * resolved values and live instances, and a library reached through a
+ * programmatic load never passed `telo check`. But the overwhelmingly common
+ * shape is two literal scalars in one flattened manifest set, which is decidable
+ * here, and a conflict is a hard BOOT failure: finding it at `telo check` is the
+ * difference between a squiggle and a deployment that will not start.
+ *
+ * Only what is DECIDABLE is compared, and the two ways it is not are skipped
+ * rather than guessed:
+ *
+ *  - A value holding a `!cel` (at any depth) is known only at load. Two
+ *    different expressions may evaluate equal, and identical text in two
+ *    different modules may not.
+ *  - A `resources:` entry names a resource by name, which means the same
+ *    instance only when both imports were DECLARED in the same module — so a
+ *    cross-module pair is left to the runtime.
+ *
+ * Grouped by the target's RESOLVED SOURCE, the identity the kernel keys its
+ * singleton registry on; `resolvedModuleName` would collapse two versions of one
+ * module, which are two libraries.
+ */
+function sharedLibraryConflicts(
+  manifests: ResourceManifest[],
+  isOwn: (module: string | undefined) => boolean,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  const byTarget = new Map<string, SuppliedConfig[]>();
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const meta = m.metadata as
+      | { name?: string; module?: string; source?: string; sharedLibrary?: boolean; resolvedSource?: string }
+      | undefined;
+    if (meta?.sharedLibrary !== true || !meta.name || !meta.resolvedSource) continue;
+    const blocks = new Map<string, Record<string, unknown>>();
+    for (const block of SUPPLIED_BLOCKS) {
+      const value = (m as Record<string, unknown>)[block];
+      blocks.set(
+        block,
+        value && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : {},
+      );
+    }
+    const bucket = byTarget.get(meta.resolvedSource);
+    const entry: SuppliedConfig = {
+      alias: meta.name,
+      module: meta.module,
+      filePath: meta.source,
+      blocks,
+    };
+    if (bucket) bucket.push(entry);
+    else byTarget.set(meta.resolvedSource, [entry]);
+  }
+
+  for (const group of byTarget.values()) {
+    if (group.length < 2) continue;
+    const [first, ...rest] = group;
+    for (const later of rest) {
+      for (const block of SUPPLIED_BLOCKS) {
+        // A reference means the same instance only within one module's scope.
+        if (block === "resources" && first!.module !== later.module) continue;
+        const a = first!.blocks.get(block)!;
+        const b = later.blocks.get(block)!;
+        for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+          if (findDynamicLeaf(a[key]) || findDynamicLeaf(b[key])) continue;
+          if (sameSuppliedValue(a[key], b[key])) continue;
+          out.push({
+            severity: DiagnosticSeverity.Error,
+            code: "SHARED_LIBRARY_CONFLICT",
+            source: SOURCE,
+            message:
+              `Import '${later.alias}' and import '${first!.alias}' both reach a ` +
+              `'lifecycle: shared' library — one instantiation for the whole application — but ` +
+              `they supply different values for ${block}.${key}. Make the two imports agree, or ` +
+              `make the library 'lifecycle: isolated'.`,
+            data: isOwn(later.module)
+              ? {
+                  resource: { kind: "Telo.Import", name: later.alias },
+                  filePath: later.filePath,
+                  path: `${block}.${key}`,
+                }
+              : {
+                  resource: { kind: "Telo.Import", name: first!.alias },
+                  filePath: first!.filePath,
+                  path: `${block}.${key}`,
+                },
+          });
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Structural equality, key-order insensitive — the analyzer's half of the rule
+ *  the kernel applies to resolved values. A secret's VALUE is compared but never
+ *  printed: the key is what the author has to look at. */
+function sameSuppliedValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => sameSuppliedValue(item, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const left = a as Record<string, unknown>;
+    const right = b as Record<string, unknown>;
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    return [...keys].every((key) => sameSuppliedValue(left[key], right[key]));
+  }
+  return false;
+}

package/src/validate-sensitive-slots.ts

@@ -0,0 +1,109 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { SCHEMA_REGION_KEYS } from "./schema-region.js";
+
+/**
+ * `x-telo-sensitive` where nothing reads it.
+ *
+ * The annotation has exactly one consumer: the kernel resolves it from a
+ * resource's bound CONTRACT — `inputType` / `outputType` — and carries the
+ * marked value as `[redacted]` in trace payloads. Written anywhere else it is an
+ * unknown keyword in an open schema, which is to say it validates, ships, and
+ * does nothing.
+ *
+ * For a security control that is the worst available failure: an author marks a
+ * token, sees no error, and puts it on the debug wire anyway. So a misplacement
+ * is reported rather than ignored — the same posture `X_TELO_REF_UNRESOLVED`
+ * takes toward a reference constraint that resolves to nothing, and for the same
+ * reason: silence reads as protection.
+ *
+ * Scoped by the caller to the entry's own modules, since a dependency's schema
+ * is not the consumer's to fix.
+ */
+export interface SensitiveSlotIssue {
+  code: "SENSITIVE_ANNOTATION_MISPLACED" | "SENSITIVE_ANNOTATION_INVALID";
+  manifest: ResourceManifest;
+  /** Dotted path to the annotated schema node. */
+  path: string;
+  message: string;
+}
+
+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: ResourceManifest): SensitiveSlotIssue[] {
+  const issues: SensitiveSlotIssue[] = [];
+
+  const walk = (node: unknown, path: (string | number)[], seen: Set<object>): void => {
+    if (!node || typeof node !== "object") return;
+    if (seen.has(node as object)) return;
+    seen.add(node as object);
+
+    if (Array.isArray(node)) {
+      node.forEach((child, i) => walk(child, [...path, i], seen));
+      return;
+    }
+
+    const record = node as Record<string, unknown>;
+    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 as unknown as Record<string, unknown>, [], 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: readonly (string | number)[]): string | undefined {
+  for (const segment of path) {
+    if (typeof segment === "string" && SCHEMA_REGION_KEYS.includes(segment)) return segment;
+  }
+  return undefined;
+}