@telorun/analyzer 0.56.1 → 0.57.0

package/src/analyzer.ts

@@ -1,7 +1,13 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId, OBSERVED_STATE_KEY } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import {
+  defaultRegistry,
+  isRefSentinel,
+  isTaggedSentinel,
+  type CelSurface,
+} from "@telorun/templating";
+import type { DiagnosticFix } from "./types.js";
 import {
   AliasResolver,
   moduleScopedDefResolver,
@@ -84,6 +90,7 @@ import {
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
 import { validateModuleArtifact } from "./validate-module-artifact.js";
+import { validateIncludePlacement } from "./validate-include-placement.js";
 import { validateModuleMetadata } from "./validate-module-metadata.js";
 import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateInvocationContract } from "./validate-invocation-contract.js";
@@ -906,89 +913,62 @@ function celAccessChains(env: Environment, expr: string): string[][] {
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 
-/** Recursively walk `data`+`schema` together, type-checking every pure CEL template
- *  string via `env.check()`. Returns `SchemaIssue[]` for any type mismatches found. */
-function collectCelTypeIssues(
+/** Restore the delimiters an engine's fix was computed without, so the
+ *  replacement is the whole scalar rather than a bare expression that would be
+ *  read back as literal text. A tagged scalar carries no wrapper and passes
+ *  through untouched. */
+function rewrapFix(
+  fix: DiagnosticFix | undefined,
+  wrapper: CelSurface["wrapper"],
+): DiagnosticFix | undefined {
+  if (!fix || !wrapper) return fix;
+  return { replacement: wrapper.prefix + fix.replacement + wrapper.suffix };
+}
+
+/** A pure-CEL leaf and the schema of the field it sits in. */
+export interface CelValueSlot {
+  readonly path: string;
+  readonly schema: Record<string, any>;
+}
+
+/** Recursively walk `data`+`schema` together, collecting every pure CEL leaf
+ *  with the schema of the field holding it.
+ *
+ *  Type *checking* is deliberately not done here. It belongs to the templating
+ *  engine, which owns the expression's syntax and now runs it once against the
+ *  environment typed for that path; checking again here would mean two verdicts
+ *  from two environments about one expression — which is exactly how an opaque
+ *  "no matching overload" used to survive next to the diagnostic that explained
+ *  it. What this walk supplies is the half the engine cannot know: the declared
+ *  type of the slot the value flows into. The comparison happens once both are
+ *  in hand (`reportCelReturnMismatches`). */
+function collectCelValueSlots(
   data: unknown,
   schema: Record<string, any>,
   path: string,
-  definition: { schema?: Record<string, any> },
-  manifest: ResourceManifest,
-  baseTypedEnv: Environment,
-  rootEnv: Environment,
-  rootModuleManifest?: ResourceManifest,
-): SchemaIssue[] {
-  const issues: SchemaIssue[] = [];
-
-  // A pure CEL value type-checks the same regardless of surface form: a
-  // `${{ … }}` string and a `!cel`-tagged sentinel must behave identically.
+): CelValueSlot[] {
+  const slots: CelValueSlot[] = [];
+
+  // A pure CEL value behaves the same regardless of surface form: a
+  // `${{ … }}` string and a `!cel`-tagged sentinel are the same expression.
   let celExpr: string | undefined;
   if (isTaggedSentinel(data)) {
     // Non-CEL engines (e.g. `!literal`) are analyzed by their own engine pass.
-    if (data.engine !== "cel") return issues;
+    if (data.engine !== "cel") return slots;
     celExpr = data.source;
   } else if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     celExpr = data.match(CEL_EXPR_RE)?.[1]?.trim();
   }
 
   if (celExpr !== undefined) {
-    {
-      const expr = celExpr;
-
-      // Merge x-telo-context variables for this path if applicable
-      let typedEnv = baseTypedEnv;
-      if (definition.schema) {
-        for (const ctx of extractContextsFromSchema(definition.schema)) {
-          if (!pathMatchesScope(path, ctx.scope)) continue;
-          typedEnv = buildTypedCelEnvironment(rootEnv, manifest, ctx.schema, rootModuleManifest);
-          break;
-        }
-      }
-
-      let checkResult: ReturnType<typeof typedEnv.check> | undefined;
-      try {
-        checkResult = typedEnv.check(expr);
-      } catch {
-        /* degrade gracefully */
-      }
-
-      if (checkResult?.valid === false && checkResult.error) {
-        // env.check() rejected the expression itself — e.g. wrong method, wrong
-        // argument types, wrong operator overload. Surface the first line of the
-        // error message; the tail is a source-code caret diagram we don't need.
-        const message = String((checkResult.error as { message?: string }).message ?? checkResult.error)
-          .split("\n")[0]
-          .trim();
-        issues.push({ message: `CEL type error: ${message}`, path });
-      } else if (checkResult?.valid && checkResult.type && schema) {
-        const celType = checkResult.type.split("<")[0]!;
-        if (!celTypeSatisfiesJsonSchema(celType, schema)) {
-          const expected = schema["x-telo-type"] ?? schema.type ?? "unknown";
-          issues.push({
-            message: `CEL returns '${checkResult.type}' but field expects '${expected}'`,
-            path,
-          });
-        }
-      }
-    }
-    return issues;
+    if (schema) slots.push({ path, schema });
+    return slots;
   }
 
   if (Array.isArray(data)) {
     const itemSchema = (schema.items ?? {}) as Record<string, any>;
     for (let i = 0; i < data.length; i++) {
-      issues.push(
-        ...collectCelTypeIssues(
-          data[i],
-          itemSchema,
-          `${path}[${i}]`,
-          definition,
-          manifest,
-          baseTypedEnv,
-          rootEnv,
-          rootModuleManifest,
-        ),
-      );
+      slots.push(...collectCelValueSlots(data[i], itemSchema, `${path}[${i}]`));
     }
   } else if (data !== null && typeof data === "object") {
     const props = (schema.properties ?? {}) as Record<string, any>;
@@ -997,22 +977,17 @@ function collectCelTypeIssues(
         ? (schema.additionalProperties as Record<string, any>)
         : {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      issues.push(
-        ...collectCelTypeIssues(
+      slots.push(
+        ...collectCelValueSlots(
           v,
           (props[k] ?? mapValueSchema) as Record<string, any>,
           path ? `${path}.${k}` : k,
-          definition,
-          manifest,
-          baseTypedEnv,
-          rootEnv,
-          rootModuleManifest,
         ),
       );
     }
   }
 
-  return issues;
+  return slots;
 }
 
 export interface StaticAnalyzerOptions {
@@ -1501,6 +1476,9 @@ export class StaticAnalyzer {
       // these fields, which is precisely why they need a check: a mistyped one
       // has no runtime failure mode that would ever surface it.
       diagnostics.push(...validateModuleMetadata(allManifests, defs, aliases));
+      // A file embed resolves at resource creation, so one written on a doc that
+      // is never instantiated is read by nothing and would ship silently.
+      diagnostics.push(...validateIncludePlacement(allManifests));
     }
     resolveSchemaTypeRefs(allManifests, aliases, aliasesByModule);
 
@@ -1638,6 +1616,19 @@ export class StaticAnalyzer {
       allManifests.find((mm) => mm.kind === "Telo.Application") ??
       allManifests.find((mm) => mm.kind === "Telo.Library");
 
+    // Every pure-CEL leaf, with the slot it flows into. Compared against the
+    // type the engine walk resolves, once both halves exist — see
+    // `collectCelValueSlots`.
+    const celReturnSlots: (CelValueSlot & {
+      manifest: ResourceManifest;
+      resource: { kind: string; name: string };
+      filePath?: string;
+    })[] = [];
+    const celTypeByPath = new Map<ResourceManifest, Map<string, string>>();
+    // Context-free typed environments, one per manifest. Reused across every
+    // expression in it — see the build site for why a matched context opts out.
+    const typedEnvByManifest = new Map<ResourceManifest, Environment>();
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       const filePath = (m.metadata as { source?: string } | undefined)?.source;
@@ -1722,7 +1713,15 @@ export class StaticAnalyzer {
           code: "UNDEFINED_KIND",
           source: SOURCE,
           message: `No Telo.Definition found for kind '${m.kind}'.${hint}`,
-          data: { resource, filePath, path: "kind", suggestedKind },
+          // `suggestedKind` is kept beside the generic `fix` because it names
+          // what the replacement IS; the fix is how to apply it.
+          data: {
+            resource,
+            filePath,
+            path: "kind",
+            suggestedKind,
+            ...(suggestedKind ? { fix: { replacement: suggestedKind } } : {}),
+          },
         });
         continue;
       }
@@ -1749,37 +1748,12 @@ export class StaticAnalyzer {
                 },
               }
             : authorSchema;
-        // Phase 1: CEL type checking — walk data+schema together, check env.check() return types.
-        // A Telo.Import's variables/secrets are a config-only contract evaluated against the
-        // IMPORTING module's scope, so type them from the owning module doc (matched by
-        // `metadata.module`) and drop `resources`/`env` so referencing them is an error. A
-        // library's own internal import is validated against that library in the library's
-        // standalone analysis; in this flattened app pass the library doc is absent, so the
-        // importer is undefined here and variables/secrets fall back to a permissive `map`
-        // (no false positives) while resources/env stay rejected.
-        const importerModule =
-          m.kind === "Telo.Import"
-            ? allManifests.find(
-                (mm) =>
-                  (mm.kind === "Telo.Application" || mm.kind === "Telo.Library") &&
-                  (mm.metadata as { name?: string } | undefined)?.name ===
-                    (m.metadata as { module?: string } | undefined)?.module,
-              )
-            : undefined;
-        const baseTypedEnv =
-          m.kind === "Telo.Import"
-            ? buildImportInputCelEnvironment(this.celEnv, importerModule)
-            : buildTypedCelEnvironment(this.celEnv, m, undefined, moduleManifest);
-        const celIssues = collectCelTypeIssues(
-          m,
-          schema,
-          "",
-          definition,
-          m,
-          baseTypedEnv,
-          this.celEnv,
-          moduleManifest,
-        );
+        // 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 });
+        }
         // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
         const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
         // Phase 4: value slots that must satisfy a type declared elsewhere on
@@ -1791,7 +1765,7 @@ export class StaticAnalyzer {
           schema,
           allManifests as Record<string, any>[],
         );
-        const issues = [...celIssues, ...ajvIssues, ...valueSchemaIssues];
+        const issues = [...ajvIssues, ...valueSchemaIssues];
         for (const issue of issues) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
@@ -2244,42 +2218,104 @@ export class StaticAnalyzer {
             });
             return;
           }
-          const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
-          for (const f of findings) {
-            if (f.code === "CEL_SYNTAX_ERROR") {
+          // The engine type-checks, so it gets the environment typed for THIS
+          // path — not the bare base one. A `Telo.Import`'s variables/secrets
+          // are a config-only contract evaluated in the IMPORTING module's
+          // scope, so they type from the owning module doc and drop
+          // `resources`/`env`, making a reference to either an error.
+          //
+          // Cached per manifest when no `x-telo-context` applied, which is most
+          // expressions: the environment then depends only on the manifest, so
+          // rebuilding it per expression is pure waste — a clone plus a
+          // re-registration of every variable, on every keystroke in the IDE.
+          // A matched context makes the environment path-specific (its schema is
+          // resolved against the enclosing array item), so those still build
+          // fresh rather than risk one item's types leaking into another's.
+          const cached = effectiveContext === null ? typedEnvByManifest.get(m) : undefined;
+          const typedEnv =
+            cached ??
+            (m.kind === "Telo.Import"
+              ? buildImportInputCelEnvironment(
+                  this.celEnv,
+                  allManifests.find(
+                    (mm) =>
+                      (mm.kind === "Telo.Application" || mm.kind === "Telo.Library") &&
+                      (mm.metadata as { name?: string } | undefined)?.name ===
+                        (m.metadata as { module?: string } | undefined)?.module,
+                  ),
+                )
+              : buildTypedCelEnvironment(
+                  this.celEnv,
+                  m,
+                  effectiveContext ?? undefined,
+                  moduleManifest,
+                ));
+          if (effectiveContext === null && !cached) typedEnvByManifest.set(m, typedEnv);
+
+          const result = engine.analyze(expr, { celEnv: typedEnv, contextSchema: effectiveContext });
+
+          if (result.type !== undefined) {
+            let byPath = celTypeByPath.get(m);
+            if (!byPath) celTypeByPath.set(m, (byPath = new Map()));
+            byPath.set(path, result.type);
+          }
+
+          // A non-deterministic call in a compile-eval field is baked once at
+          // load: `nowIso()` there freezes at boot. Sometimes that is the
+          // 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)) {
+            const volatile = [
+              ...new Set(result.calls.filter((c) => c.deterministic === false).map((c) => c.name)),
+            ].sort();
+            if (volatile.length > 0) {
               diagnostics.push({
-                severity: DiagnosticSeverity.Error,
-                code: "CEL_SYNTAX_ERROR",
+                severity: DiagnosticSeverity.Warning,
+                code: "CEL_NONDETERMINISTIC_IN_COMPILE_FIELD",
                 source: SOURCE,
-                message: `CEL syntax error at ${path}: ${f.message}`,
+                message: `${m.kind}/${resource.name}: '${path}' is evaluated once at startup, so ${volatile.map((n) => `\`${n}()\``).join(", ")} ${volatile.length === 1 ? "is" : "are"} baked in at load and never re-evaluated. Move the expression to a field evaluated per call (x-telo-eval: runtime) if it should change over time.`,
                 data: { resource, filePath, path },
               });
-            } else if (f.code === "CEL_UNKNOWN_FIELD") {
+            }
+          }
+
+          for (const f of result.diagnostics) {
+            // A repair is applicable only when the analyzed expression covers
+            // the whole scalar. For one `${{ }}` among literal text, replacing
+            // the node would drop the text around it, so the correction stays
+            // in the message and no fix is stamped.
+            const fix = e.surface.whole ? rewrapFix(f.fix, e.surface.wrapper) : undefined;
+            const data = { resource, filePath, path, ...(fix ? { fix } : {}) };
+            if (f.code === "CEL_SYNTAX_ERROR") {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: "CEL_UNKNOWN_FIELD",
+                code: "CEL_SYNTAX_ERROR",
                 source: SOURCE,
-                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
-                data: { resource, filePath, path },
+                message: `CEL syntax error at ${path}: ${f.message}`,
+                data,
               });
-            } else if (f.code === "CEL_NULLABLE_ACCESS") {
+            } else if (f.code === undefined) {
+              // No code from a future engine — pass the message through, tagged
+              // with a generic ENGINE_DIAGNOSTIC code so downstream filters can
+              // still bucket it.
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: "CEL_NULLABLE_ACCESS",
+                code: "ENGINE_DIAGNOSTIC",
                 source: SOURCE,
-                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
-                data: { resource, filePath, path },
+                message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+                data,
               });
             } else {
-              // Unknown code from a future engine — pass the message through,
-              // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
-              // filters can still bucket it.
+              // Named by ENGINE, not hardcoded to CEL: the seam exists so a
+              // second engine can produce coded findings, and labelling them
+              // `CEL` would misattribute the first one that does.
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: f.code ?? "ENGINE_DIAGNOSTIC",
+                code: f.code,
                 source: SOURCE,
                 message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
-                data: { resource, filePath, path },
+                data,
               });
             }
           }
@@ -2288,6 +2324,24 @@ export class StaticAnalyzer {
       { aliases },
     );
 
+    // The two halves of "does this expression fit the slot it flows into" meet
+    // here: the engine resolved the expression's type during the walk above,
+    // and the schema walk recorded the slot. An expression that failed to check
+    // recorded no type and is already reported by its own diagnostic.
+    for (const slot of celReturnSlots) {
+      const type = celTypeByPath.get(slot.manifest)?.get(slot.path);
+      if (type === undefined) continue;
+      if (celTypeSatisfiesJsonSchema(type.split("<")[0]!, slot.schema)) continue;
+      const expected = slot.schema["x-telo-type"] ?? slot.schema.type ?? "unknown";
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "CEL_TYPE_ERROR",
+        source: SOURCE,
+        message: `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' returns '${type}' but the field expects '${expected}'.`,
+        data: { resource: slot.resource, filePath: slot.filePath, path: slot.path },
+      });
+    }
+
     // Validate resource references (Phase 3)
     diagnostics.push(
       ...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }),

package/src/index.ts

@@ -207,6 +207,8 @@ export type {
   PlatformAxis,
   PlatformTarget,
 } from "./artifact-selector.js";
+export { collectModuleFileClaims } from "./module-file-claims.js";
+export type { ModuleFileClaim } from "./module-file-claims.js";
 export {
   LayerIndexError,
   matchControllerLayers,
@@ -224,10 +226,12 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
 export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export type { CelNode, CelSegment } from "./cel-ast.js";
-export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
+export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions,
+    DiagnosticData,
+    DiagnosticFix,
     LoaderInitOptions,
     LoadOptions,
     ManifestSource,

package/src/manifest-visitor.ts

@@ -1,5 +1,10 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
+import {
+  isRefSentinel,
+  isTaggedSentinel,
+  walkCelExpressions,
+  type CelSurface,
+} from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -114,6 +119,9 @@ export interface CelSiteEvent {
   contextSchema?: Record<string, any>;
   /** Scope of the matched context (e.g. `$.routes[*].handler`), if matched. */
   matchedScope?: string;
+  /** Where `expr` sits in the scalar at `path`, and the delimiters to restore
+   *  around a corrected expression. See `CelSurface`. */
+  surface: CelSurface;
 }
 
 export interface ManifestVisitor {
@@ -352,7 +360,7 @@ export function visitManifest(
 
     if (wantsCel) {
       const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
-      walkCelExpressions(r, "", (expr, path, engineName) => {
+      walkCelExpressions(r, "", (expr, path, engineName, surface) => {
         let contextSchema: Record<string, any> | undefined;
         let matchedScope: string | undefined;
         for (const ctx of contexts) {
@@ -362,7 +370,7 @@ export function visitManifest(
             break;
           }
         }
-        visitor.onCel!({ source: r, path, expr, engineName, contextSchema, matchedScope });
+        visitor.onCel!({ source: r, path, expr, engineName, contextSchema, matchedScope, surface });
       });
     }
 

package/src/module-file-claims.ts

@@ -0,0 +1,168 @@
+import {
+  defaultCustomTags,
+  defaultRegistry,
+  walkCelExpressions,
+  type TemplatingEngineRegistry,
+} from "@telorun/templating";
+import { PackageURL } from "packageurl-js";
+import { parseAllDocuments } from "yaml";
+import { selectorFromQualifiers, selectorKey, type ArtifactSelector } from "./artifact-selector.js";
+
+/**
+ * One module-relative file a manifest names, and the artifact layer it belongs
+ * to.
+ *
+ * The single answer to "why is this file in the payload", replacing two
+ * derivations that happened to agree: publish used to re-parse the manifest with
+ * PURL knowledge hardcoded into the CLI, and any second vocabulary — a tag that
+ * embeds a file, say — would have had to be added there by hand. Here the
+ * knowledge sits with whoever owns the syntax: a controller candidate is read by
+ * this module, and a tagged value is read by the engine that owns its tag, via
+ * `TemplatingEngine.fileClaims`. Publish maps role to layer and recognises
+ * neither.
+ *
+ * Deliberately NOT hung off `analyze()`. That pass runs over a flattened,
+ * import-inclusive manifest set, so its claims would mix in imported libraries'
+ * files — whose paths are relative to *their* module and must never join this
+ * artifact — and it would make packaging, today derivable offline from manifest
+ * text, a product of resolving the whole import graph. This is per-module by
+ * construction and needs nothing but the text.
+ *
+ * Browser-safe, like the rest of the analyzer: parsing and string work only, no
+ * filesystem. Whether a claimed file EXISTS is a separate question, asked by the
+ * Node-side caller that has a directory to look in.
+ */
+interface ClaimBase {
+  /** Module-root-relative POSIX path — relative to the directory holding
+   *  `telo.yaml`, never to the file the claim was written in. Publish inlines
+   *  every `include:` partial into the published `telo.yaml`, so a
+   *  per-file-relative path would change meaning in the artifact. */
+  readonly path: string;
+  /** Where the claim came from, for diagnostics: the PURL, or `!<tag>` and the
+   *  path of the value that carried it. */
+  readonly origin: string;
+}
+
+/**
+ * A **discriminated union**, not one shape with optional fields: a controller
+ * layer is one per selector and carries sibling patterns, and an assets layer is
+ * neither. Optional fields on a single shape put the consumer one `!` away from
+ * a crash inside `selectorKey` with no useful message, and let a producer emit a
+ * controller claim with no selector that nothing would reject.
+ */
+export type ModuleFileClaim =
+  | (ClaimBase & {
+      readonly role: "controller";
+      readonly selector: ArtifactSelector;
+      /** Extra payload patterns that belong in the same layer as this claim —
+       *  `.gitignore`-style globs over the selected files, matched by the
+       *  caller, which is the side that knows what was selected. */
+      readonly siblings: readonly string[];
+    })
+  | (ClaimBase & { readonly role: "assets" });
+
+/** `pkg:telo/local/<format>?path=…` — the bundled-controller delivery mode.
+ *  Anything else (`pkg:npm`, `pkg:cargo`) fetches from its own ecosystem and
+ *  contributes no layer. */
+const BUNDLED_TYPE = "telo";
+const BUNDLED_NAMESPACE = "local";
+
+/** Qualifier naming extra files that belong in a controller's layer — what an
+ *  entry point loads but the manifest cannot otherwise see (a `.wasm` beside its
+ *  glue, a native library opened at runtime). */
+const SIBLINGS_QUALIFIER = "siblings";
+
+/** Normalize a `path=` / sibling value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value: string): string {
+  return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+
+/** Bundled-controller claims from one document's `controllers:` list. */
+function controllerClaims(json: unknown): ModuleFileClaim[] {
+  const candidates = (json as { controllers?: unknown } | null)?.controllers;
+  if (!Array.isArray(candidates)) return [];
+  const claims: ModuleFileClaim[] = [];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string") continue;
+    let parsed: PackageURL;
+    try {
+      parsed = PackageURL.fromString(candidate);
+    } catch {
+      // Not a parseable PURL — claim collection is not the place to reject it;
+      // the analyzer's own validation and the controller loader both report it
+      // with better context.
+      continue;
+    }
+    if (parsed.type !== BUNDLED_TYPE || parsed.namespace !== BUNDLED_NAMESPACE) continue;
+    const entry = parsed.qualifiers?.path;
+    if (typeof entry !== "string" || entry === "") continue;
+    claims.push({
+      role: "controller",
+      path: normalizeRelative(entry),
+      selector: selectorFromQualifiers(parsed.name, parsed.qualifiers, `controller "${candidate}"`),
+      siblings: String(parsed.qualifiers?.[SIBLINGS_QUALIFIER] ?? "")
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p !== ""),
+      origin: candidate,
+    });
+  }
+  return claims;
+}
+
+/** Claims contributed by tagged values, asked of the engine that owns each tag.
+ *  The walk reaches every tagged scalar in the document, so an engine that
+ *  embeds files is discovered wherever its tag was written.
+ *
+ *  The layer role is assigned HERE, not by the engine: an engine reports what it
+ *  embeds, and which layer that belongs in is this module's vocabulary. A file a
+ *  tag embeds is read only when the resource holding it is created, so `assets`
+ *  — the lazily-fetched layer — is what it is. */
+function taggedClaims(json: unknown, registry: TemplatingEngineRegistry): ModuleFileClaim[] {
+  const claims: ModuleFileClaim[] = [];
+  walkCelExpressions(json, "", (source, path, engineName) => {
+    const engine = registry.get(engineName);
+    for (const claim of engine?.fileClaims?.(source) ?? []) {
+      claims.push({ role: "assets", path: claim.path, origin: `!${engineName} at '${path}'` });
+    }
+  });
+  return claims;
+}
+
+/** Identity of a claim for de-duplication: the same file claimed twice by two
+ *  resources is one file in one layer. Role and selector are part of it because
+ *  a file two controller candidates both claim is genuinely copied into each of
+ *  their layers — dropping one would leave a platform's layer short a file it
+ *  declared it needs. */
+function claimKey(claim: ModuleFileClaim): string {
+  const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+  return `${claim.role}\0${selector}\0${claim.path}`;
+}
+
+/**
+ * Every module-relative file the manifest names, from every syntax that can name
+ * one.
+ *
+ * `manifestText` is one module's `telo.yaml`. Publish passes the text it is
+ * about to ship — i.e. after `include:` partials have been inlined — but the
+ * answer does not depend on that: claims are root-relative, so collecting them
+ * before or after inlining gives the same set.
+ */
+export function collectModuleFileClaims(
+  manifestText: string,
+  registry: TemplatingEngineRegistry = defaultRegistry(),
+): ModuleFileClaim[] {
+  const seen = new Set<string>();
+  const claims: ModuleFileClaim[] = [];
+  for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+    const json = doc.toJSON() as unknown;
+    for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+      const key = claimKey(claim);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      claims.push(claim);
+    }
+  }
+  return claims;
+}