@telorun/analyzer 0.67.0 → 0.69.0

package/src/reconcile-module-versions.ts

@@ -50,15 +50,14 @@ interface ModuleIdentity {
  *  **What this key cannot relate.** It compares ref *spellings*, so it groups by
  *  origin exactly and nothing else. Two consequences, both accepted:
  *
- *  - A module imported once by a registry ref and once by a relative path is two
- *    groups, so a version skew between them is not hoisted. Keying on what the
- *    module declares about itself would catch that case, but only by trusting a
- *    self-declared identity — which is what this change removes, and which
- *    cannot tell two same-named modules from different origins apart.
- *  - A bare `std/kv-store@0.4.0` and the equivalent direct
- *    `https://<registry>/std/kv-store/0.4.0/telo.yaml` are two groups. Relating
- *    them needs the configured registry base, which this pure, browser-safe
- *    function does not have. */
+ *  - A module imported once by an `oci://` ref and once by a relative path is
+ *    two groups, so a version skew between them is not hoisted. Keying on what
+ *    the module declares about itself would catch that case, but only by
+ *    trusting a self-declared identity — which is what this change removes, and
+ *    which cannot tell two same-named modules from different origins apart.
+ *  - An `oci://` ref and a direct `https://…/telo.yaml` URL serving the same
+ *    module are two groups. Relating them needs knowledge of the origin's
+ *    layout, which this pure, browser-safe function does not have. */
 function refIdentity(ref: string): string | null {
   const base = ref.split("#")[0];
   if (!base || base.startsWith(".") || base.startsWith("/") || base.startsWith("file:")) {
@@ -185,8 +184,8 @@ export function reconcileModuleVersions(
   // source normally maps to exactly one identity; the entry module has no
   // inbound edge and needs none (it is never reconciled against itself).
   //
-  // One source CAN be reached by two spellings of the same location (a bare
-  // registry ref and the direct URL it resolves to). Both name the same module
+  // One source CAN be reached by two spellings of the same location (a ref and
+  // the direct URL it resolves to). Both name the same module
   // at the same version, so either identity groups it correctly — but the choice
   // must not depend on edge iteration order, or the same graph could reconcile
   // differently across runs. First edge wins.

package/src/release/release-plan.ts

@@ -60,7 +60,7 @@ export interface ModuleEvidence {
   readonly inlines: ReadonlyMap<ModuleKey, readonly string[]>;
   /**
    * Modules reached by an in-repo **relative** `imports:` source. A pinned
-   * registry ref is deliberately not an edge: pinning is the statement "I am not
+   * remote ref is deliberately not an edge: pinning is the statement "I am not
    * affected until I choose to be", and moving it is `telo upgrade`'s job.
    */
   readonly imports: readonly ModuleKey[];

package/src/resolve-zone-containment.ts

@@ -195,8 +195,16 @@ function collect(
   }
 }
 
+/** A region as the WALK finds it, before any attribute is asked for: the slot
+ *  that opens it and everything it reaches. Every attribute query is a filter
+ *  over these, so a consumer wanting regions regardless of what they declare —
+ *  an editor drawing the enclosure, where a zone declaring no attribute is
+ *  still a zone — reads them directly instead of enumerating the vocabulary and
+ *  silently missing whatever is not in it. */
+export type ZoneProvider = Omit<ZoneRegion, "attribute" | "reason">;
+
 /**
- * Every region in the graph opened by a slot declaring `attribute`.
+ * Every region in the graph, keyed by the slot that opens it.
  *
  * The provider itself is NOT in `contents` — a zone constrains what runs inside
  * its body, not the resource that establishes it. A transaction's own
@@ -204,12 +212,11 @@ function collect(
  * treated the provider as contained would report the provider against its own
  * constraint.
  */
-export function findZoneRegions(
+export function findZoneProviders(
   graph: CallGraph,
   resolveDef: DefinitionLookup,
-  attribute: string,
-): ZoneRegion[] {
-  const regions: ZoneRegion[] = [];
+): ZoneProvider[] {
+  const regions: ZoneProvider[] = [];
 
   for (const node of graph.nodes.values()) {
     if (node.type !== "resource") continue;
@@ -221,8 +228,7 @@ export function findZoneRegions(
     // properties rather than by knowing any kind's field names.
     for (const [slot, slotSchema] of providingSlots(rootSchema)) {
       const provides = readProvidesZone(slotSchema);
-      const reason = provides?.attributes[attribute as keyof typeof provides.attributes];
-      if (!provides || typeof reason !== "string") continue;
+      if (!provides) continue;
 
       const contents = new Map<string, ContainedNode>();
       const boundaries: RegionBoundary[] = [];
@@ -257,8 +263,6 @@ export function findZoneRegions(
       }
 
       regions.push({
-        attribute,
-        reason,
         provider: node,
         slot,
         attributes: provides.attributes as Readonly<Record<string, string>>,
@@ -271,6 +275,42 @@ export function findZoneRegions(
   return regions;
 }
 
+/**
+ * Every region opened by a slot declaring `attribute`.
+ *
+ * A filter over {@link findZoneProviders}, so the walk is stated once: what an
+ * attribute query adds is which regions are in scope and the author's `reason`,
+ * which is the attribute's own value.
+ *
+ * **The provider list is memoized per graph**, because the filter made the walk
+ * unconditional: it used to skip the containment BFS for any provider not
+ * declaring the queried attribute, and six queries per analysis (four zone
+ * attributes plus two durable ones) became six full walks over every provider
+ * in the module. The cache is keyed on the CallGraph object, which is itself
+ * built once per analysis — so it lives exactly as long as the answer stays
+ * true, and a rebuilt graph gets a fresh one.
+ */
+const providersByGraph = new WeakMap<CallGraph, ZoneProvider[]>();
+
+export function findZoneRegions(
+  graph: CallGraph,
+  resolveDef: DefinitionLookup,
+  attribute: string,
+): ZoneRegion[] {
+  let providers = providersByGraph.get(graph);
+  if (!providers) {
+    providers = findZoneProviders(graph, resolveDef);
+    providersByGraph.set(graph, providers);
+  }
+  const out: ZoneRegion[] = [];
+  for (const region of providers) {
+    const reason = region.attributes[attribute];
+    if (typeof reason !== "string") continue;
+    out.push({ ...region, attribute, reason });
+  }
+  return out;
+}
+
 /** Field-map paths of every slot in a kind's schema carrying a provides-zone
  *  annotation, with the schema node at each. Walks properties, array items and
  *  `additionalProperties`, resolving local `$ref`s — the paths the call graph's

package/src/resolve-zone-requirements.ts

@@ -308,7 +308,12 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
       const local = scopeLocal.get(`${from.scopeOwner}\0${from.scopeSite}`)?.get(name);
       if (local) return local;
     }
-    return graph.resourceByName(name);
+    // In the scope that WROTE the name: a bare reference means the reader's own
+    // module, and two libraries may each declare one.
+    return graph.resourceByName(
+      name,
+      (from.manifest.metadata as { module?: string } | undefined)?.module,
+    );
   };
 
   const acceptedFor = (zone: string): ReadonlySet<string> => {
@@ -809,7 +814,7 @@ export function runZoneAnalysis(args: ZoneAnalysisArgs): AnalysisDiagnostic[] {
   for (const lib of rootLibraries) {
     for (const [exportName, specs] of openExports) {
       if (!lib.exportedNames.has(exportName)) continue;
-      const node = graph.resourceByName(exportName);
+      const node = graph.resourceByName(exportName, lib.module);
       if (!node || (node.manifest.metadata as { module?: string } | undefined)?.module !== lib.module) {
         continue;
       }

package/src/schema-keywords.ts

@@ -27,6 +27,9 @@
  */
 
 import { X_TELO_TYPE } from "@telorun/sdk";
+
+/** The one annotation read from a DATA schema rather than a kind schema. */
+const X_TELO_SENSITIVE = "x-telo-sensitive" as const;
 import { ANNOTATION_KEYWORDS } from "./value-type-keyword.js";
 
 /** A keyword entry: the JSON Schema its VALUE must satisfy, carrying the title
@@ -227,7 +230,13 @@ export function jsonSchemaKeywords(self: string): SchemaKeywords {
  * a schema describing an annotation from an annotation, which nothing does yet.
  */
 export const TELO_SCHEMA_ANNOTATIONS: Record<
-  (typeof ANNOTATION_KEYWORDS)[number] | typeof X_TELO_TYPE,
+  // Exhaustive over the kind vocabulary, so adding a keyword without an entry is
+  // a compile error. `x-telo-sensitive` is excluded because it belongs to the
+  // DATA vocabulary below — it is read from a contract, not from a kind's own
+  // `schema:` — and offering it here would put it on the one schema where
+  // nothing reads it.
+  | Exclude<(typeof ANNOTATION_KEYWORDS)[number], typeof X_TELO_SENSITIVE>
+  | typeof X_TELO_TYPE,
   Record<string, unknown>
 > = {
   "x-telo-eval": {
@@ -381,3 +390,26 @@ export const TELO_SCHEMA_ANNOTATIONS: Record<
     type: "string",
   },
 };
+
+/**
+ * Annotations that belong on a DATA schema — an `inputType` / `outputType`
+ * contract — rather than on a kind's own `schema:`.
+ *
+ * Split out because {@link TELO_SCHEMA_ANNOTATIONS} is offered only where the
+ * fragment is `KindSchema`, which is a kind's CONFIGURATION. `x-telo-sensitive`
+ * is read from the opposite place: the kernel resolves it off a bound contract,
+ * which stamps `JsonSchema7`. Offering it from the kind vocabulary alone put it
+ * on the one schema where nothing reads it and withheld it from the two where it
+ * is the whole mechanism.
+ */
+export const TELO_DATA_SCHEMA_ANNOTATIONS: Record<
+  typeof X_TELO_SENSITIVE,
+  Record<string, unknown>
+> = {
+  [X_TELO_SENSITIVE]: {
+    title: "Sensitive",
+    description:
+      "This value is auth material or equivalent: carry it as `[redacted]` in trace payloads and on the debug wire rather than verbatim. Read only from a resource's declared `inputType` / `outputType`.",
+    type: "boolean",
+  },
+};

package/src/sources/default-sources.ts

@@ -1,12 +1,11 @@
 import type { ManifestSource } from "../types.js";
 import { HttpSource } from "./http-source.js";
-import { RegistrySource } from "./registry-source.js";
 
-/** The browser-safe built-in sources, in resolution order: HTTP fetch then
- *  registry. Node-specific sources (local filesystem) are supplied by the
- *  consuming package and passed alongside these into the `Loader` constructor.
- *  Callers that only want a subset (e.g. the editor, which brings its own
- *  registry adapters) construct the individual sources directly. */
-export function defaultSources(registryUrl?: string): ManifestSource[] {
-  return [new HttpSource(), new RegistrySource(registryUrl)];
+/** The browser-safe built-in sources. Node-specific sources (local filesystem)
+ *  are supplied by the consuming package and passed alongside these into the
+ *  `Loader` constructor. Callers that only want a subset (e.g. the editor, which
+ *  brings its own manifest-cache adapter) construct the individual sources
+ *  directly. */
+export function defaultSources(): ManifestSource[] {
+  return [new HttpSource()];
 }

package/src/sources/integrity.ts

@@ -110,11 +110,26 @@ export async function verifyIntegrity(
   }
 }
 
+/** Object-storage backends (Cloudflare R2, S3) surface auth and permission
+ *  failures as a **200 with an XML error body**. Caught here rather than left to
+ *  the loader, which would parse the XML as YAML and report a downstream
+ *  `UNDEFINED_KIND` — naming the manifest's contents as the problem instead of
+ *  the origin that refused to serve it. Returns the failure detail, or `null`
+ *  when the body is not an XML error document. */
+function objectStorageError(text: string): string | null {
+  const head = text.trimStart();
+  if (!head.startsWith("<?xml") && !head.startsWith("<Error")) return null;
+  const code = text.match(/<Code>([^<]+)<\/Code>/);
+  const message = text.match(/<Message>([^<]+)<\/Message>/);
+  return code && message ? `${code[1]}: ${message[1]}` : text.slice(0, 200);
+}
+
 /** The single verified network read for remote manifests: fetch `fetchUrl`,
  *  verify the raw bytes against `integrity` (when pinned), and return both the
  *  bytes and the decoded text. The one choke point every network `ManifestSource`
- *  routes through, so verification cannot drift between them. `describe` names
- *  the artifact in error messages. */
+ *  routes through, so verification cannot drift between them — which is also why
+ *  the object-storage non-manifest check lives here rather than in each source.
+ *  `describe` names the artifact in error messages. */
 export async function verifiedFetch(
   fetchUrl: string,
   integrity: string | undefined,
@@ -127,6 +142,16 @@ export async function verifiedFetch(
     );
   }
   const bytes = new Uint8Array(await response.arrayBuffer());
+  const text = new TextDecoder().decode(bytes);
+  // Before the integrity check: a bucket's error page hashes to something, and
+  // reporting a pin mismatch would name the wrong cause just as the loader does.
+  const storageError = objectStorageError(text);
+  if (storageError) {
+    throw new Error(
+      `The origin returned a non-manifest response for ${describe} ` +
+        `(URL: ${fetchUrl}): ${storageError}`,
+    );
+  }
   if (integrity) await verifyIntegrity(bytes, integrity, describe);
-  return { bytes, text: new TextDecoder().decode(bytes) };
+  return { bytes, text };
 }

package/src/sources/versioned-ref.ts

@@ -1,16 +1,15 @@
 import { splitIntegrity } from "./integrity.js";
-import { isRegistryRef } from "./module-ref.js";
 import { OCI_SCHEME } from "./oci-ref.js";
 
 /** A module ref split into the parts an upgrade needs: the version-independent
  *  ref, the version segment it currently names, and any inline pin. */
 export interface ParsedVersionedRef {
   /** The ref with its `@version` segment and integrity fragment removed —
-   *  `std/run`, `oci://ghcr.io/telorun/timer`. This is the identity a version
-   *  list is keyed by (the hub registers modules under exactly this form). */
+   *  `oci://ghcr.io/telorun/timer`. This is the identity a version list is keyed
+   *  by (the hub registers modules under exactly this form). */
   baseRef: string;
-  /** The version segment, raw — a registry `@version`, an OCI tag, or an OCI
-   *  digest reference (`sha256:…`). The caller applies its own SemVer check. */
+  /** The version segment, raw — an OCI tag or an OCI digest reference
+   *  (`sha256:…`). The caller applies its own SemVer check. */
   version: string;
   /** Telo's inline `sha256-<base64url>` pin, when the ref carried one. */
   integrity?: string;
@@ -20,12 +19,17 @@ export interface ParsedVersionedRef {
  *  upgradeable version — a local path, a bare `https://` URL, or an OCI ref
  *  with no explicit reference (an implicit `latest` is not a pin).
  *
- *  Browser-safe and transport-neutral: this is the *grammar* half of an
- *  upgrade, shared by the kernel transports (whose `refVersion` / `withVersion`
- *  delegate here) and the editor, which cannot use a transport at all — the
- *  *network* half (enumerating versions) is scheme-specific and stays behind
- *  `Transport.listVersions` on Node and the hub's `/module/versions` in the
- *  browser. */
+ *  Browser-safe: this is the *grammar* half of an upgrade, shared by the kernel
+ *  transports (whose `refVersion` / `withVersion` delegate here) and the editor,
+ *  which cannot use a transport at all — the *network* half (enumerating
+ *  versions) is scheme-specific and stays behind `Transport.listVersions` on
+ *  Node and the hub's `/module/versions` in the browser.
+ *
+ *  It is NOT transport-neutral: `oci://` is the only versionable grammar, named
+ *  literally below. That was equally true when the registry ref was the second
+ *  branch, and a third scheme still means editing this file — the versionable
+ *  set would have to become data the transports contribute before that claim
+ *  could be made honestly. */
 export function parseVersionedRef(ref: string): ParsedVersionedRef | null {
   const { base, integrity } = splitIntegrity(ref);
   const at = versionSeparator(base);
@@ -41,37 +45,31 @@ export function parseVersionedRef(ref: string): ParsedVersionedRef | null {
  *
  *  Throws when the ref's grammar has no version segment at all — a relative
  *  path, a bare `https://` URL. Producing `../lib@0.4.0` for those would write
- *  a ref nothing can resolve, so this fails where the transport-specific
- *  parsers it replaced (`parseOciRef` / `parseModuleRef`) also failed. */
+ *  a ref nothing can resolve, so this fails where the transport-specific parser
+ *  it replaced (`parseOciRef`) also failed. */
 export function withRefVersion(ref: string, version: string): string {
   const { base } = splitIntegrity(ref);
-  if (refGrammar(base) === null) {
+  if (!isVersionableRef(base)) {
     throw new Error(
-      `Cannot set a version on '${ref}' — only registry (namespace/name@version) ` +
-        `and oci:// refs carry a version segment.`,
+      `Cannot set a version on '${ref}' — only oci:// refs carry a version segment.`,
     );
   }
   const at = versionSeparator(base);
   return `${at === null ? base : base.slice(0, at)}@${version}`;
 }
 
-/** Which versionable ref grammar `base` is written in, or `null` when it is
- *  neither — a relative/absolute path, a `file:`/`https://` URL. */
-function refGrammar(base: string): "oci" | "registry" | null {
-  if (base.startsWith(OCI_SCHEME)) {
-    // A host alone is not addressable; the repo path is what carries a version.
-    return base.indexOf("/", OCI_SCHEME.length) > OCI_SCHEME.length ? "oci" : null;
-  }
-  // `isRegistryRef` requires the `@`, so a version-less `std/console` is not a
-  // registry ref by this test — matching `parseModuleRef`, which throws on it.
-  return isRegistryRef(base) ? "registry" : null;
+/** True when `base` is written in a grammar that carries a version segment — a
+ *  relative/absolute path and a `file:`/`https://` URL are not. */
+function isVersionableRef(base: string): boolean {
+  // A host alone is not addressable; the repo path is what carries a version.
+  return base.startsWith(OCI_SCHEME) && base.indexOf("/", OCI_SCHEME.length) > OCI_SCHEME.length;
 }
 
 /** Index of the `@` that separates the version, or `null` when the ref names
  *  none. Split on the LAST `@` so a digest reference (`repo@sha256:…`) keeps
  *  everything before it as the ref. */
 function versionSeparator(base: string): number | null {
-  if (refGrammar(base) === null) return null;
+  if (!isVersionableRef(base)) return null;
   const at = base.lastIndexOf("@");
-  return at > (base.startsWith(OCI_SCHEME) ? OCI_SCHEME.length : 0) ? at : null;
+  return at > OCI_SCHEME.length ? at : null;
 }

package/src/telo-version.ts

@@ -6,4 +6,4 @@
 // written against, and every kernel in every language reports the same scale.
 
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.83.0";
+export const TELO_SURFACE_VERSION = "0.85.0";

package/src/validate-extends.ts

@@ -1,7 +1,13 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
-import { inheritedCapability, type DefResolver } from "./extends-resolution.js";
+import {
+  controllerBearingAncestor,
+  effectiveAuthorSchema,
+  inheritedCapability,
+  isInheritedDelegation,
+  type DefResolver,
+} from "./extends-resolution.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -25,6 +31,9 @@ const EXTENDS_ALIAS_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
  *  - EXTENDS_UNKNOWN_TARGET: alias resolves to a module, but that module has no
  *    registered definition with the target name.
  *  - EXTENDS_NON_ABSTRACT: target resolves to a Telo.Definition, not a Telo.Abstract.
+ *  - EXTENDS_CLOSED_PARENT_ADDS_FIELD: a child with no `base:` declares a property its
+ *    controller-bearing ancestor's closed schema rejects — the runtime counterpart is a
+ *    create-time failure phrased against the ancestor kind.
  *  - CAPABILITY_SHADOWS_EXTENDS (warning): `capability` names a user-declared abstract
  *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
  *    never trigger this — they're lifecycle roles by design.
@@ -149,6 +158,47 @@ export function validateExtends(
                   data: { resource, filePath, path: "capability" },
                 });
               }
+
+              // A merge-form child (no `base:`) forwards its WHOLE config to the
+              // inherited controller as the parent's config, so a field the
+              // parent's schema closes out is rejected at the parent's own
+              // create-time validation — phrased against the parent kind, at the
+              // instance's line, about a resource the author never wrote.
+              // Reported here instead, at the property that has to change.
+              if (
+                (m as { base?: unknown }).base == null &&
+                isInheritedDelegation(m as ResourceDefinition, resolveDef)
+              ) {
+                const ancestor = controllerBearingAncestor(m as ResourceDefinition, resolveDef);
+                const ancestorSchema = ancestor
+                  ? effectiveAuthorSchema(ancestor, resolveDef)
+                  : undefined;
+                if (ancestorSchema?.additionalProperties === false) {
+                  const inherited = new Set(Object.keys(ancestorSchema.properties ?? {}));
+                  const ownProps = ((m as { schema?: { properties?: Record<string, unknown> } })
+                    .schema?.properties ?? {}) as Record<string, unknown>;
+                  const ancestorKind = `${ancestor?.metadata.module}.${ancestor?.metadata.name}`;
+                  for (const prop of Object.keys(ownProps)) {
+                    if (inherited.has(prop)) continue;
+                    diagnostics.push({
+                      severity: DiagnosticSeverity.Error,
+                      code: "EXTENDS_CLOSED_PARENT_ADDS_FIELD",
+                      source: SOURCE,
+                      message:
+                        `${label}: declares '${prop}', but '${ancestorKind}' closes its schema ` +
+                        `(additionalProperties: false) and a child without 'base:' forwards its whole ` +
+                        `config as that kind's config — so '${prop}' is rejected when the resource is ` +
+                        `created. Add a 'base:' mapping, which makes this kind's fields construction ` +
+                        `inputs and builds the parent's config explicitly.`,
+                      data: {
+                        resource,
+                        filePath,
+                        path: `schema.properties.${prop}`,
+                      },
+                    });
+                  }
+                }
+              }
             }
           }
         }

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;
+}

package/src/value-type-keyword.ts

@@ -69,6 +69,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/dist/sources/module-ref.d.ts

@@ -1,21 +0,0 @@
-/** A parsed registry module reference. `modulePath` is `namespace/name`,
- *  `version` has any leading `v` stripped, and `integrity` carries the inline
- *  `sha256-<base64url>` hash when the ref was pinned. */
-export interface ParsedModuleRef {
-    modulePath: string;
-    version: string;
-    integrity?: string;
-}
-/** True when `url` has the bare registry-ref shape `namespace/name@version`
- *  (no scheme of any kind, no leading `/` or `.`, contains both `@` and `/`).
- *  The integrity fragment, if any, does not affect the classification.
- *
- *  A registry ref never carries a `scheme://` — that guard is what keeps an
- *  `oci://…@ver` (or future `s3://…`) ref from being misrouted here, so a
- *  scheme-owning transport claims it instead. */
-export declare function isRegistryRef(url: string): boolean;
-/** Canonical parser for `namespace/name@version[#sha256-...]` refs. The single
- *  source of truth shared by the registry source, the kernel manifest cache,
- *  and the CLI (install / upgrade / bundle). Throws on a malformed ref. */
-export declare function parseModuleRef(ref: string): ParsedModuleRef;
-//# sourceMappingURL=module-ref.d.ts.map

package/dist/sources/module-ref.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"module-ref.d.ts","sourceRoot":"","sources":["../../src/sources/module-ref.ts"],"names":[],"mappings":"AAEA;;yDAEyD;AACzD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASlD;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAgB3D"}

package/dist/sources/module-ref.js

@@ -1,36 +0,0 @@
-import { splitIntegrity } from "./integrity.js";
-/** True when `url` has the bare registry-ref shape `namespace/name@version`
- *  (no scheme of any kind, no leading `/` or `.`, contains both `@` and `/`).
- *  The integrity fragment, if any, does not affect the classification.
- *
- *  A registry ref never carries a `scheme://` — that guard is what keeps an
- *  `oci://…@ver` (or future `s3://…`) ref from being misrouted here, so a
- *  scheme-owning transport claims it instead. */
-export function isRegistryRef(url) {
-    const { base } = splitIntegrity(url);
-    return (!base.includes("://") &&
-        !base.startsWith("/") &&
-        !base.startsWith(".") &&
-        base.includes("@") &&
-        base.includes("/"));
-}
-/** Canonical parser for `namespace/name@version[#sha256-...]` refs. The single
- *  source of truth shared by the registry source, the kernel manifest cache,
- *  and the CLI (install / upgrade / bundle). Throws on a malformed ref. */
-export function parseModuleRef(ref) {
-    const { base, integrity } = splitIntegrity(ref);
-    const atIdx = base.lastIndexOf("@");
-    if (atIdx <= 0 || atIdx === base.length - 1) {
-        throw new Error(`Invalid module reference '${ref}', expected namespace/name@version`);
-    }
-    const modulePath = base.slice(0, atIdx);
-    if (!modulePath.includes("/")) {
-        throw new Error(`Invalid module reference '${ref}', expected namespace/name@version`);
-    }
-    const rawVersion = base.slice(atIdx + 1);
-    const version = rawVersion.startsWith("v") ? rawVersion.slice(1) : rawVersion;
-    if (!version) {
-        throw new Error(`Invalid module reference '${ref}', expected namespace/name@version`);
-    }
-    return { modulePath, version, integrity };
-}