@telorun/ide-support 0.5.0 → 0.7.0

package/src/completions/import-source.ts

@@ -1,8 +1,9 @@
-import type { CompletionResult, IdeEnvironmentAdapter } from "../types.js";
+import type { CompletionResult, IdeEnvironmentAdapter, ReplaceRange } from "../types.js";
 
-/** Maximum registry hits to surface in a single completion request.
- *  Keeps the popover scannable when a broad `q=` query matches the catalog. */
-const REGISTRY_LIMIT = 50;
+/** Maximum ref hits to surface in a single completion request. Keeps the
+ *  popover scannable when a broad `q=` query matches many registered refs
+ *  (the hub already caps `/refs` server-side; this is a client backstop). */
+const REF_LIMIT = 50;
 
 /** Caps the number of directory entries we probe with `hasManifest` per
  *  request. Each probe is a host-side filesystem stat; the popover would not
@@ -17,17 +18,21 @@ const PATH_PROBE_LIMIT = 50;
  * Branches by prefix shape:
  *   ""                         → relative dirs under the manifest dir, plus `./` / `../` seeds.
  *   "./..", "../", "/..."      → subdirs of the typed path (any subdir; existing manifest gets a hint).
- *   "<word>"                   → registry search by free-text.
- *   "<ns>/<name>@<partial>"    → version list for that module.
- *   "http(s)://", "file://"    → no suggestions (opaque URLs).
+ *   "<word>", "oci://…"        → hub ref autocomplete (fuzzy substring over registered refs).
+ *   "<ref>@<partial>"          → version list for that ref.
+ *   "http(s)://", "file://"    → no suggestions (opaque URLs the author types verbatim).
  *
- * `valueStartColumn` is forwarded onto every result so the host can replace
- * the whole typed value, not just the trailing word (Monaco / VSCode word
- * boundaries don't cross `/` or `@`).
+ * `oci://` is deliberately NOT opaque: without an `@` it routes to the ref
+ * search below, whose query is the whole typed prefix — so the hub fuzzy-matches
+ * `oci://ghcr.io/aws/telo-s3` as readily as a bare `s3`.
+ *
+ * `replaceRange` is forwarded onto every result so the host replaces the whole
+ * value, not just the trailing word (Monaco / VSCode word boundaries don't
+ * cross `/` or `@`).
  */
 export async function importSourceCompletions(
   prefix: string,
-  valueStartColumn: number,
+  replaceRange: ReplaceRange,
   adapter: IdeEnvironmentAdapter | undefined,
 ): Promise<CompletionResult[]> {
   if (!adapter) return [];
@@ -43,20 +48,22 @@ export async function importSourceCompletions(
   const isRelativeShape =
     prefix === "" || prefix.startsWith(".") || prefix.startsWith("/");
   if (isRelativeShape) {
-    return relativePathCompletions(prefix, valueStartColumn, adapter);
+    return relativePathCompletions(prefix, replaceRange, adapter);
   }
 
-  const atIdx = prefix.indexOf("@");
+  // The version (or `@sha256:` digest) is the trailing `@`-segment, so split on
+  // the LAST `@` — a digest-pinned ref keeps everything before it as the ref.
+  const atIdx = prefix.lastIndexOf("@");
   if (atIdx > 0) {
-    return versionCompletions(prefix, atIdx, valueStartColumn, adapter);
+    return versionCompletions(prefix, atIdx, replaceRange, adapter);
   }
 
-  return registrySearchCompletions(prefix, valueStartColumn, adapter);
+  return refSearchCompletions(prefix, replaceRange, adapter);
 }
 
 async function relativePathCompletions(
   prefix: string,
-  valueStartColumn: number,
+  replaceRange: ReplaceRange,
   adapter: IdeEnvironmentAdapter,
 ): Promise<CompletionResult[]> {
   // Empty prefix → seed `./` and `../` so the user gets traction; otherwise
@@ -69,14 +76,14 @@ async function relativePathCompletions(
         kind: "folder",
         insertText: "./",
         sortText: "0_./",
-        replaceFromColumn: valueStartColumn,
+        replaceRange,
       },
       {
         label: "../",
         kind: "folder",
         insertText: "../",
         sortText: "0_../",
-        replaceFromColumn: valueStartColumn,
+        replaceRange,
       },
     ];
   }
@@ -111,7 +118,7 @@ async function relativePathCompletions(
         detail: isModule ? "telo module" : "folder",
         insertText: fullPath,
         filterText: fullPath,
-        replaceFromColumn: valueStartColumn,
+        replaceRange,
         // Modules sort above plain folders so they surface first when the user
         // is browsing a `modules/` tree mixed with non-Telo siblings.
         sortText: isModule ? `0_${name}` : `1_${name}`,
@@ -120,65 +127,76 @@ async function relativePathCompletions(
   );
 }
 
-async function registrySearchCompletions(
+async function refSearchCompletions(
   prefix: string,
-  valueStartColumn: number,
+  replaceRange: ReplaceRange,
   adapter: IdeEnvironmentAdapter,
 ): Promise<CompletionResult[]> {
-  // The registry's `q` filter ILIKEs against name / namespace / description —
-  // it doesn't know about the `<namespace>/<name>` shape. Once the user has
-  // typed a `/`, sending the literal `std/htt` as `q` matches nothing because
-  // the slash is not in any of those columns. Split here so `q` carries just
-  // the bit that looks like a name, and apply the namespace constraint
-  // client-side.
-  const slashIdx = prefix.indexOf("/");
-  const namespacePart = slashIdx >= 0 ? prefix.slice(0, slashIdx) : "";
-  const namePart = slashIdx >= 0 ? prefix.slice(slashIdx + 1) : prefix;
-
-  const hits = await adapter.searchRegistry(namePart);
-  const filtered = namespacePart
-    ? hits.filter((h) => h.namespace.startsWith(namespacePart))
-    : hits;
-
-  return filtered.slice(0, REGISTRY_LIMIT).map((m) => {
-    const id = `${m.namespace}/${m.name}@${m.version}`;
+  // The whole typed prefix is the fuzzy query — the hub matches it as a
+  // substring over each registered ref, so no client-side splitting is needed
+  // (and `oci://ghcr.io/aws/telo-s3` matches without mangling the `//`).
+  const hits = await adapter.searchRefs(prefix);
+
+  return hits.slice(0, REF_LIMIT).map((m) => {
+    // Seed the pinned `ref@latestVersion` so the completion is directly usable;
+    // the author can still narrow the version afterwards (the `@` re-triggers
+    // version completion).
+    const id = m.latestVersion ? `${m.ref}@${m.latestVersion}` : m.ref;
+    const name = refDisplayName(m.ref);
+    // Lead the label with the module name so the interesting part isn't cut off
+    // behind the transport/host boilerplate (`oci://ghcr.io/telorun/…`). The
+    // full ref moves to `detail`, and `insertText`/`filterText` stay the ref so
+    // acceptance still inserts it and a fully-typed ref still filters.
     return {
-      label: id,
+      label: m.latestVersion ? `${name}@${m.latestVersion}` : name,
       kind: "module",
-      detail: m.description ?? "registry module",
+      detail: m.description ?? m.ref,
+      documentation: m.description ? m.ref : undefined,
       insertText: id,
       filterText: id,
-      replaceFromColumn: valueStartColumn,
+      replaceRange,
     };
   });
 }
 
+/** The `org/name` tail of a location ref: its last two path segments, with the
+ *  transport scheme (`oci://`, `https://`, …) and registry host dropped.
+ *  `oci://ghcr.io/telorun/telo-console` → `telorun/telo-console`; `std/console`
+ *  → `std/console`. Falls back to fewer segments (or the whole ref) when there
+ *  aren't two. */
+function refDisplayName(ref: string): string {
+  const withoutScheme = ref.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+  const segments = withoutScheme.split("/").filter(Boolean);
+  return segments.slice(-2).join("/") || ref;
+}
+
 async function versionCompletions(
   prefix: string,
   atIdx: number,
-  valueStartColumn: number,
+  replaceRange: ReplaceRange,
   adapter: IdeEnvironmentAdapter,
 ): Promise<CompletionResult[]> {
-  const beforeAt = prefix.slice(0, atIdx);
+  const ref = prefix.slice(0, atIdx);
   const partialVersion = prefix.slice(atIdx + 1);
-  const slashIdx = beforeAt.indexOf("/");
-  if (slashIdx <= 0 || slashIdx === beforeAt.length - 1) return [];
+  if (ref === "") return [];
 
-  const namespace = beforeAt.slice(0, slashIdx);
-  const name = beforeAt.slice(slashIdx + 1);
-  const versions = await adapter.listRegistryVersions(namespace, name);
+  const versions = await adapter.listVersionsForRef(ref);
 
   const matches = versions.filter((v) => v.startsWith(partialVersion));
   return matches.map((version, idx) => {
-    const id = `${namespace}/${name}@${version}`;
+    const id = `${ref}@${version}`;
+    // The ref is already typed and visible on the line, so the label is just the
+    // version — no point repeating the full ref on every row. `insertText` /
+    // `filterText` stay the full id so acceptance replaces the whole value and
+    // the already-typed ref prefix keeps the item in the filtered set.
     return {
-      label: id,
+      label: version,
       kind: "value",
-      detail: idx === 0 ? "latest" : `v${version}`,
+      detail: idx === 0 ? "latest" : undefined,
       insertText: id,
       filterText: id,
-      replaceFromColumn: valueStartColumn,
-      // Preserve registry's ordering (newest first) so the latest version is
+      replaceRange,
+      // Preserve the hub's ordering (newest first) so the latest version is
       // suggested at the top regardless of lexical comparison.
       sortText: String(idx).padStart(4, "0"),
     };

package/src/completions/resolve-node.ts

@@ -0,0 +1,405 @@
+import {
+  buildLineOffsets,
+  offsetToPosition,
+  type AstDocument,
+  type AstMap,
+  type AstNode,
+  type AstScalar,
+  type CelSegment,
+  type Position,
+} from "@telorun/analyzer";
+
+/** The cursor's resolved position against the read-only AST. `locate` produces
+ *  this; `detect-context` maps it onto a `CompletionCtx`. Structure comes from
+ *  the AST; the cursor *column* is used only to resolve empty-space (blank /
+ *  trailing-indent) key positions, where indentation is the sole signal for
+ *  "which container am I typing into". */
+export interface ResolvedCursor {
+  docIndex: number;
+  /** Top-level `kind:` value of the cursor's document, when present. */
+  docKind?: string;
+  slot: "key" | "value";
+  /** Value slot: ancestor keys + the field key (last element is the field).
+   *  Key slot: the container map's ancestor key chain. */
+  path: string[];
+  node?: AstNode;
+  container?: AstMap;
+  replaceRange?: { start: Position; end: Position };
+  /** Value slot: text from the value start up to the cursor. */
+  prefix?: string;
+  /** Value slot: true when whitespace separates the key's colon from the value
+   *  (distinguishes `Console: ` — a value — from `Tiny:` — a bare header). */
+  spaceAfterColon?: boolean;
+  /** Value slot: the value of a sibling `kind:` in the same map (object-form
+   *  ref name completion). */
+  siblingKind?: string;
+  /** Key slot: keys already present in the container (the key under the cursor
+   *  excluded so it still suggests itself). */
+  existingKeys?: Set<string>;
+  /** Key slot: the kind of the nearest enclosing inline resource (or the root
+   *  resource), whose schema the prop keys are completed against. Falls back to
+   *  the document kind at the root. */
+  resourceKind?: string;
+  /** Key slot: number of `path` segments that reach `resourceKind`'s map, so
+   *  the schema-relative path is `path.slice(resourceDepth)`. */
+  resourceDepth?: number;
+  /** Set when the cursor sits inside a CEL body (closed or open). Populated for
+   *  a future CEL-completion feature; this refactor does not consume it. */
+  cel?: { segment: CelSegment; offset: number };
+}
+
+function within(range: [number, number], offset: number): boolean {
+  return offset >= range[0] && offset <= range[1];
+}
+
+export function scalarString(node: AstNode | undefined): string | undefined {
+  if (node?.kind === "scalar" && typeof node.value === "string") return node.value;
+  return undefined;
+}
+
+/** The `kind:` value of a document's root map, if any. */
+function docKindOf(doc: AstDocument): string | undefined {
+  if (doc.root?.kind !== "map") return undefined;
+  for (const pair of doc.root.entries) {
+    if (scalarString(pair.key) === "kind") return scalarString(pair.value);
+  }
+  return undefined;
+}
+
+/** Value of a sibling `kind:` entry in `map`, for object-form ref detection. */
+function siblingKindOf(map: AstMap): string | undefined {
+  for (const pair of map.entries) {
+    if (scalarString(pair.key) === "kind") return scalarString(pair.value);
+  }
+  return undefined;
+}
+
+/** The map's `kind:` value when it names a resource kind (`Alias.Kind`), i.e.
+ *  the map is an inline resource. A prop-key position inside such a map is
+ *  completed against *this* kind's schema, not the outer ref slot's. */
+function resourceKindOf(map: AstMap): string | undefined {
+  const kind = siblingKindOf(map);
+  return kind && /^\w+\.\w+/.test(kind) ? kind : undefined;
+}
+
+/** The kind + path-depth of the nearest enclosing inline resource (or the root
+ *  resource). `depth` is the number of `path` segments consumed to reach that
+ *  map, so a prop-key `yamlPath` relative to it is `path.slice(depth)`. */
+interface ResourceScope {
+  kind?: string;
+  depth: number;
+}
+
+function enter(scope: ResourceScope, map: AstMap, ancestorsLen: number): ResourceScope {
+  const kind = resourceKindOf(map);
+  return kind ? { kind, depth: ancestorsLen } : scope;
+}
+
+// ---------------------------------------------------------------------------
+// Containment descent — used for the cursor sitting ON a real node.
+// ---------------------------------------------------------------------------
+
+type Descent =
+  | {
+      type: "key";
+      container: AstMap;
+      path: string[];
+      keyNode: AstScalar;
+      keyName?: string;
+      scope: ResourceScope;
+    }
+  | {
+      type: "value";
+      /** The enclosing map, or `undefined` for a bare scalar sequence item
+       *  (which has no keyed siblings). */
+      container: AstMap | undefined;
+      path: string[];
+      keyName?: string;
+      keyEnd: number;
+      valueNode: AstNode;
+    }
+  | { type: "empty" };
+
+function descend(
+  node: AstNode,
+  ancestors: string[],
+  offset: number,
+  scope: ResourceScope,
+): Descent | undefined {
+  if (node.kind === "map") {
+    const mapScope = enter(scope, node, ancestors.length);
+    for (const pair of node.entries) {
+      const keyName = scalarString(pair.key);
+      if (within(pair.key.range, offset)) {
+        return {
+          type: "key",
+          container: node,
+          path: ancestors,
+          keyNode: pair.key as AstScalar,
+          keyName,
+          scope: mapScope,
+        };
+      }
+      if (pair.value && within(pair.value.range, offset)) {
+        const childAncestors = keyName != null ? [...ancestors, keyName] : ancestors;
+        if (pair.value.kind === "map" || pair.value.kind === "seq") {
+          return descend(pair.value, childAncestors, offset, mapScope) ?? { type: "empty" };
+        }
+        return {
+          type: "value",
+          container: node,
+          path: ancestors,
+          keyName,
+          keyEnd: pair.key.range[1],
+          valueNode: pair.value,
+        };
+      }
+    }
+    return undefined;
+  }
+  if (node.kind === "seq") {
+    // Sequence items are transparent to the key path (mirrors the schema
+    // walker, which auto-descends arrays).
+    for (const item of node.items) {
+      if (within(item.range, offset)) {
+        if (item.kind === "map" || item.kind === "seq") {
+          return descend(item, ancestors, offset, scope) ?? { type: "empty" };
+        }
+        // A bare scalar list item (`targets:\n  - One`) has no enclosing map of
+        // keyed siblings — leave `container` undefined rather than treating the
+        // seq as a map.
+        return { type: "value", container: undefined, path: ancestors, keyEnd: item.range[0], valueNode: item };
+      }
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Column search — used for empty-space (blank / trailing-indent) key positions.
+// ---------------------------------------------------------------------------
+
+interface MapScope {
+  path: string[];
+  childColumn: number;
+  keys: Set<string>;
+  rangeStart: number;
+  scope: ResourceScope;
+}
+
+interface PairScope {
+  path: string[]; // full key path to this pair
+  keyColumn: number;
+  keyOffset: number;
+  childKeys: Set<string>;
+  scope: ResourceScope;
+}
+
+function collectScopes(
+  node: AstNode,
+  ancestors: string[],
+  scope: ResourceScope,
+  lineOffsets: number[],
+  maps: MapScope[],
+  pairs: PairScope[],
+): void {
+  if (node.kind === "map") {
+    const mapScope = enter(scope, node, ancestors.length);
+    const keys = new Set<string>();
+    let childColumn = -1;
+    for (const pair of node.entries) {
+      const keyName = scalarString(pair.key);
+      if (keyName != null) keys.add(keyName);
+      if (childColumn < 0) childColumn = offsetToPosition(pair.key.range[0], lineOffsets).character;
+    }
+    if (childColumn >= 0) {
+      maps.push({ path: ancestors, childColumn, keys, rangeStart: node.range[0], scope: mapScope });
+    }
+    for (const pair of node.entries) {
+      const keyName = scalarString(pair.key);
+      const fullPath = keyName != null ? [...ancestors, keyName] : ancestors;
+      const childKeys = new Set<string>();
+      if (pair.value?.kind === "map") {
+        for (const p of pair.value.entries) {
+          const k = scalarString(p.key);
+          if (k != null) childKeys.add(k);
+        }
+      }
+      pairs.push({
+        path: fullPath,
+        keyColumn: offsetToPosition(pair.key.range[0], lineOffsets).character,
+        keyOffset: pair.key.range[0],
+        childKeys,
+        scope: mapScope,
+      });
+      if (pair.value) collectScopes(pair.value, fullPath, mapScope, lineOffsets, maps, pairs);
+    }
+  } else if (node.kind === "seq") {
+    for (const item of node.items) collectScopes(item, ancestors, scope, lineOffsets, maps, pairs);
+  }
+}
+
+interface KeyResolution {
+  path: string[];
+  existingKeys: Set<string>;
+  scope: ResourceScope;
+}
+
+/** Resolve the container a new key at `cursorColumn` belongs to. Prefers an
+ *  existing sibling level (a map whose child keys sit at exactly `cursorColumn`);
+ *  otherwise nests under the nearest-preceding shallower key. */
+function columnSearch(
+  root: AstNode,
+  cursorColumn: number,
+  cursorOffset: number,
+  lineOffsets: number[],
+): KeyResolution {
+  const maps: MapScope[] = [];
+  const pairs: PairScope[] = [];
+  collectScopes(root, [], { depth: 0 }, lineOffsets, maps, pairs);
+
+  // Sibling level: a map whose children already sit at the cursor's column.
+  let sibling: MapScope | undefined;
+  for (const m of maps) {
+    if (m.childColumn === cursorColumn && m.rangeStart < cursorOffset) {
+      if (!sibling || m.rangeStart > sibling.rangeStart) sibling = m;
+    }
+  }
+  if (sibling) return { path: sibling.path, existingKeys: sibling.keys, scope: sibling.scope };
+
+  // Nest under the nearest-preceding key shallower than the cursor.
+  let nest: PairScope | undefined;
+  for (const p of pairs) {
+    if (p.keyColumn < cursorColumn && p.keyOffset < cursorOffset) {
+      if (
+        !nest ||
+        p.keyColumn > nest.keyColumn ||
+        (p.keyColumn === nest.keyColumn && p.keyOffset > nest.keyOffset)
+      ) {
+        nest = p;
+      }
+    }
+  }
+  if (nest) return { path: nest.path, existingKeys: nest.childKeys, scope: nest.scope };
+
+  return { path: [], existingKeys: new Set(), scope: { depth: 0 } };
+}
+
+// ---------------------------------------------------------------------------
+
+function selectDoc(docs: AstDocument[], offset: number): number {
+  let best = -1;
+  for (let i = 0; i < docs.length; i++) {
+    if (docs[i].range[0] <= offset) best = i;
+  }
+  return best < 0 ? (docs.length > 0 ? 0 : -1) : best;
+}
+
+function celAt(node: AstScalar, offset: number): ResolvedCursor["cel"] {
+  for (const segment of node.celSegments()) {
+    if (offset >= segment.range[0] && offset <= segment.range[1]) return { segment, offset };
+  }
+  return undefined;
+}
+
+/** Resolve `(line, character)` against the AST (Approach B: AST for structure,
+ *  cursor column only to place empty-space key positions). */
+export function resolveNodeAtPosition(
+  text: string,
+  docs: AstDocument[],
+  line: number,
+  character: number,
+): ResolvedCursor | undefined {
+  if (docs.length === 0) return undefined;
+  const lineOffsets = buildLineOffsets(text);
+  const offset = (lineOffsets[line] ?? 0) + character;
+  const toPos = (o: number): Position => offsetToPosition(o, lineOffsets);
+
+  const docIndex = selectDoc(docs, offset);
+  if (docIndex < 0) return undefined;
+  const doc = docs[docIndex];
+  const docKind = docKindOf(doc);
+
+  const found = doc.root ? descend(doc.root, [], offset, { depth: 0 }) : undefined;
+
+  // Cursor sits on an existing map key → key/prop-key position.
+  if (found?.type === "key") {
+    const existingKeys = new Set<string>();
+    for (const pair of found.container.entries) {
+      const k = scalarString(pair.key);
+      if (k != null && k !== found.keyName) existingKeys.add(k);
+    }
+    return {
+      docIndex,
+      docKind,
+      slot: "key",
+      path: found.path,
+      node: found.keyNode,
+      replaceRange: { start: toPos(found.keyNode.range[0]), end: toPos(found.keyNode.range[1]) },
+      container: found.container,
+      existingKeys,
+      resourceKind: found.scope.kind,
+      resourceDepth: found.scope.depth,
+    };
+  }
+
+  // Cursor sits on a scalar value.
+  if (found?.type === "value" && found.valueNode.kind === "scalar") {
+    const value = found.valueNode;
+    const cel = celAt(value, offset);
+    // A bare identifier on its own line with no colon is a partial *key* being
+    // typed as a first child (yaml parses it as the parent's value). Route to a
+    // key position via column search — the documented cursor-line carve-out.
+    const lineText = text.slice(lineOffsets[line] ?? 0, lineOffsets[line + 1] ?? text.length);
+    const isPartialKey =
+      typeof value.value === "string" &&
+      !lineText.includes(":") &&
+      /^\s*[A-Za-z_][\w-]*\s*$/.test(lineText) &&
+      toPos(value.range[0]).line !== toPos(found.keyEnd).line;
+    if (isPartialKey && doc.root) {
+      const col = toPos(value.range[0]).character;
+      const { path, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
+      return {
+        docIndex,
+        docKind,
+        slot: "key",
+        path,
+        container: found.container,
+        existingKeys,
+        resourceKind: scope.kind,
+        resourceDepth: scope.depth,
+      };
+    }
+
+    const clampedEnd = Math.min(offset, value.range[1]);
+    return {
+      docIndex,
+      docKind,
+      slot: "value",
+      path: found.keyName != null ? [...found.path, found.keyName] : found.path,
+      node: value,
+      container: found.container,
+      prefix: text.slice(value.range[0], clampedEnd),
+      spaceAfterColon: value.range[0] - found.keyEnd >= 2,
+      siblingKind: found.container ? siblingKindOf(found.container) : undefined,
+      replaceRange: { start: toPos(value.range[0]), end: toPos(value.range[1]) },
+      cel,
+    };
+  }
+
+  // Empty space (blank line, trailing indent, empty document) → key position,
+  // resolved by cursor column.
+  const resolution: KeyResolution = doc.root
+    ? columnSearch(doc.root, character, offset, lineOffsets)
+    : { path: [], existingKeys: new Set<string>(), scope: { depth: 0 } };
+  return {
+    docIndex,
+    docKind,
+    slot: "key",
+    path: resolution.path,
+    existingKeys: resolution.existingKeys,
+    resourceKind: resolution.scope.kind,
+    resourceDepth: resolution.scope.depth,
+  };
+}

package/src/completions/valid-capabilities.ts

@@ -6,3 +6,14 @@ export const CAPABILITY_VALUES = [
   "Telo.Mount",
   "Telo.Type",
 ] as const;
+
+/** One-line role summary per capability, surfaced on hover. Kept in sync with
+ *  the capability list in `CLAUDE.md` / the kernel builtins. */
+export const CAPABILITY_DOCS: Record<string, string> = {
+  "Telo.Service": "Long-lived resource: `init()` + optional `teardown()` (servers, pools).",
+  "Telo.Runnable": "One-shot task: `run()` (pipelines, boot steps).",
+  "Telo.Invocable": "Request handler: `invoke(inputs)` (scripts, endpoints).",
+  "Telo.Provider": "Value-flow source: `init()` + optional `provide()` (config, secrets).",
+  "Telo.Mount": "Mounted into a Service (HTTP APIs, middleware).",
+  "Telo.Type": "Pure schema definition — no runtime instance.",
+};