@telorun/analyzer 0.1.1

package/dist/builtins.js

@@ -0,0 +1,109 @@
+export const KERNEL_BUILTINS = [
+    { kind: "Kernel.Abstract", metadata: { name: "Template", module: "Kernel" } },
+    { kind: "Kernel.Abstract", metadata: { name: "Runnable", module: "Kernel" } },
+    { kind: "Kernel.Abstract", metadata: { name: "Service", module: "Kernel" } },
+    { kind: "Kernel.Abstract", metadata: { name: "Invocable", module: "Kernel" } },
+    { kind: "Kernel.Abstract", metadata: { name: "Mount", module: "Kernel" } },
+    { kind: "Kernel.Abstract", metadata: { name: "Type", module: "Kernel" } },
+    {
+        kind: "Kernel.Abstract",
+        metadata: { name: "Provider", module: "Kernel" },
+        schema: { "x-telo-eval": "compile" },
+    },
+    {
+        kind: "Kernel.Definition",
+        metadata: { name: "Abstract", module: "Kernel" },
+        capability: "Kernel.Template",
+        schema: {
+            type: "object",
+            properties: {
+                kind: { type: "string" },
+                metadata: {
+                    type: "object",
+                    properties: { name: { type: "string" } },
+                    required: ["name"],
+                    additionalProperties: true,
+                },
+                capability: { type: "string" },
+            },
+            required: ["metadata"],
+            additionalProperties: false,
+        },
+    },
+    {
+        kind: "Kernel.Definition",
+        metadata: { name: "Definition", module: "Kernel" },
+        capability: "Kernel.Template",
+        schema: { type: "object" },
+    },
+    {
+        kind: "Kernel.Definition",
+        metadata: { name: "Import", module: "Kernel" },
+        capability: "Kernel.Template",
+        schema: {
+            type: "object",
+            properties: {
+                kind: { type: "string" },
+                metadata: {
+                    type: "object",
+                    properties: { name: { type: "string" } },
+                    required: ["name"],
+                    additionalProperties: true,
+                },
+                source: { type: "string" },
+                variables: { type: "object" },
+                secrets: { type: "object" },
+            },
+            required: ["metadata", "source"],
+            additionalProperties: false,
+        },
+    },
+    {
+        kind: "Kernel.Definition",
+        metadata: { name: "Module", module: "Kernel" },
+        capability: "Kernel.Template",
+        schema: {
+            type: "object",
+            properties: {
+                kind: { type: "string" },
+                metadata: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string" },
+                        version: { type: "string" },
+                        source: { type: "string" },
+                        module: { type: "string" },
+                    },
+                    required: ["name"],
+                    additionalProperties: true,
+                },
+                lifecycle: {
+                    type: "string",
+                    enum: ["shared", "isolated"],
+                    default: "shared",
+                },
+                keepAlive: { type: "boolean", default: false },
+                variables: { type: "object" },
+                secrets: { type: "object" },
+                targets: {
+                    type: "array",
+                    items: {
+                        anyOf: [
+                            { type: "string", "x-telo-ref": "kernel#Runnable" },
+                            { type: "string", "x-telo-ref": "kernel#Service" },
+                        ],
+                    },
+                },
+                exports: {
+                    type: "object",
+                    properties: {
+                        kinds: { type: "array", items: { type: "string" } },
+                    },
+                    additionalProperties: true,
+                },
+            },
+            required: ["metadata"],
+            additionalProperties: false,
+        },
+    },
+];

package/dist/cel-environment.d.ts

@@ -0,0 +1,12 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { Environment } from "@marcbachmann/cel-js";
+export declare const celEnvironment: Environment;
+/** Clone `celEnvironment` and register typed variable declarations so that
+ *  `env.check(expr)` can infer return types for expressions referencing known variables.
+ *
+ *  - `variables`: typed from the manifest's `variables` field if it is a schema map
+ *    (only `Kernel.Module` resources carry this); otherwise registered as `map` (dyn).
+ *  - `secrets`, `resources`, `imports`, `env`: always `map` (dyn — output schemas unknown).
+ *  - `extraContextSchema`: additional variables from an `x-telo-context` annotation. */
+export declare function buildTypedCelEnvironment(manifest: ResourceManifest, extraContextSchema?: Record<string, any> | null): Environment;
+//# sourceMappingURL=cel-environment.d.ts.map

package/dist/cel-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,eAAO,MAAM,cAAc,aAWvB,CAAC;AAEL;;;;;;wFAMwF;AACxF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAC9C,WAAW,CA0Cb"}

package/dist/cel-environment.js

@@ -0,0 +1,59 @@
+import { Environment } from "@marcbachmann/cel-js";
+import { jsonSchemaToCelType } from "./schema-compat.js";
+export const celEnvironment = new Environment({ unlistedVariablesAreDyn: true })
+    .registerFunction("join(list, string): string", (list, sep) => list.map(String).join(sep))
+    .registerFunction("keys(map): list", (map) => {
+    if (map instanceof Map)
+        return [...map.keys()];
+    return Object.keys(map);
+})
+    .registerFunction("values(map): list", (map) => {
+    if (map instanceof Map)
+        return [...map.values()];
+    return Object.values(map);
+});
+/** Clone `celEnvironment` and register typed variable declarations so that
+ *  `env.check(expr)` can infer return types for expressions referencing known variables.
+ *
+ *  - `variables`: typed from the manifest's `variables` field if it is a schema map
+ *    (only `Kernel.Module` resources carry this); otherwise registered as `map` (dyn).
+ *  - `secrets`, `resources`, `imports`, `env`: always `map` (dyn — output schemas unknown).
+ *  - `extraContextSchema`: additional variables from an `x-telo-context` annotation. */
+export function buildTypedCelEnvironment(manifest, extraContextSchema) {
+    try {
+        const env = celEnvironment.clone();
+        // Build typed ObjectSchema from manifest.variables if it looks like a schema map
+        const vars = manifest.variables;
+        if (vars !== null && typeof vars === "object" && !Array.isArray(vars)) {
+            const entries = Object.entries(vars).filter(([, v]) => v !== null && typeof v === "object" && !Array.isArray(v));
+            if (entries.length > 0) {
+                const schema = {};
+                for (const [k, v] of entries) {
+                    schema[k] = jsonSchemaToCelType(v);
+                }
+                env.registerVariable({ name: "variables", schema });
+            }
+            else {
+                env.registerVariable("variables", "map");
+            }
+        }
+        else {
+            env.registerVariable("variables", "map");
+        }
+        env.registerVariable("secrets", "map");
+        env.registerVariable("resources", "map");
+        env.registerVariable("imports", "map");
+        env.registerVariable("env", "map");
+        if (extraContextSchema?.properties) {
+            for (const [name, propSchema] of Object.entries(extraContextSchema.properties)) {
+                if (!env.hasVariable(name)) {
+                    env.registerVariable(name, jsonSchemaToCelType(propSchema));
+                }
+            }
+        }
+        return env;
+    }
+    catch {
+        return celEnvironment.clone();
+    }
+}

package/dist/definition-registry.d.ts

@@ -0,0 +1,58 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+import { type ReferenceFieldMap } from "./reference-field-map.js";
+/** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
+export declare class DefinitionRegistry {
+    constructor();
+    /** Per-instance AJV for cross-module $ref resolution. Isolated so each registry
+     *  (and thus each AnalysisContext) has its own schema store — no stale schemas
+     *  across analyze() calls and no unbounded growth across the process lifetime. */
+    private readonly ajv;
+    private readonly registeredSchemaIds;
+    private readonly defs;
+    private readonly fieldMaps;
+    /** Reverse inheritance index: parent kind → direct child kinds. */
+    private readonly extendedBy;
+    /** Module identity table: identity string → canonical module name.
+     *  "kernel" → "Kernel", "std/pipeline" → "pipeline", etc. */
+    private readonly identityMap;
+    /** Reverse identity table: canonical module name → full identity string.
+     *  "Kernel" → "kernel", "pipeline" → "std/pipeline", etc.
+     *  Used to compute definition $id values for the AJV schema store. */
+    private readonly reverseIdentityMap;
+    register(definition: ResourceDefinition): void;
+    /** Register a module identity for x-telo-ref resolution.
+     *  Call once per Kernel.Module manifest when the manifest is loaded.
+     *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for kernel built-ins.
+     *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
+    registerModuleIdentity(namespace: string | null, moduleName: string): void;
+    /** Computes the $id for a definition schema: "<identity>/<TypeName>".
+     *  Returns undefined when the module identity is not yet registered. */
+    computeId(moduleName: string, typeName: string): string | undefined;
+    /** Validates data against a schema using this registry's AJV instance, which has all
+     *  registered definition schemas loaded — enabling cross-module $ref resolution. */
+    validateWithRefs(data: unknown, schema: Record<string, any>): string[];
+    private tryRegisterSchema;
+    /** Resolves an x-telo-ref string to a canonical registry kind key.
+     *  Splits on "#", looks up the left side in the identity table, and returns
+     *  "<canonicalModule>.<TypeName>".
+     *
+     *  "kernel#Invocable"       → "Kernel.Invocable"
+     *  "std/pipeline#Job"       → "pipeline.Job"
+     *  "std/http-server#Server" → "http-server.Server"
+     *
+     *  Returns undefined when the string is malformed or the identity is not registered. */
+    resolveRef(xTeloRef: string): string | undefined;
+    resolve(kind: string): ResourceDefinition | undefined;
+    /** Returns the cached reference field map for the given kind, built once during register(). */
+    getFieldMap(kind: string): ReferenceFieldMap | undefined;
+    /** Returns the field map for `kind`, falling back to the alias-resolved kind when not found. */
+    getFieldMapForKind(kind: string, aliases?: {
+        resolveKind(k: string): string | undefined;
+    }): ReferenceFieldMap | undefined;
+    /** Returns all definitions that transitively extend the given abstract kind.
+     *  Follows the capability chain to any depth (equivalent to instanceof in OOP).
+     *  Definitions are included regardless of registration order. */
+    getByExtends(abstractKind: string): ResourceDefinition[];
+    kinds(): string[];
+}
+//# sourceMappingURL=definition-registry.d.ts.map

package/dist/definition-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG1F,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;iEAC6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD;;0EAEsE;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAwB9C;;;yFAGqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgB1E;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;wFACoF;IACpF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;4FAQwF;IACxF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD,+FAA+F;IAC/F,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}

package/dist/definition-registry.js

@@ -0,0 +1,155 @@
+import { KERNEL_BUILTINS } from "./builtins.js";
+import { buildReferenceFieldMap } from "./reference-field-map.js";
+import { createAjv, formatSingleError } from "./schema-compat.js";
+/** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
+export class DefinitionRegistry {
+    constructor() {
+        for (const def of KERNEL_BUILTINS)
+            this.register(def);
+    }
+    /** Per-instance AJV for cross-module $ref resolution. Isolated so each registry
+     *  (and thus each AnalysisContext) has its own schema store — no stale schemas
+     *  across analyze() calls and no unbounded growth across the process lifetime. */
+    ajv = createAjv();
+    registeredSchemaIds = new Set();
+    defs = new Map();
+    fieldMaps = new Map();
+    /** Reverse inheritance index: parent kind → direct child kinds. */
+    extendedBy = new Map();
+    /** Module identity table: identity string → canonical module name.
+     *  "kernel" → "Kernel", "std/pipeline" → "pipeline", etc. */
+    identityMap = new Map();
+    /** Reverse identity table: canonical module name → full identity string.
+     *  "Kernel" → "kernel", "pipeline" → "std/pipeline", etc.
+     *  Used to compute definition $id values for the AJV schema store. */
+    reverseIdentityMap = new Map();
+    register(definition) {
+        const { name, module: mod } = definition.metadata;
+        const key = mod ? `${mod}.${name}` : name;
+        this.defs.set(key, definition);
+        this.fieldMaps.set(key, buildReferenceFieldMap(definition.schema ?? {}));
+        if (definition.capability) {
+            const children = this.extendedBy.get(definition.capability);
+            if (children) {
+                children.push(key);
+            }
+            else {
+                this.extendedBy.set(definition.capability, [key]);
+            }
+        }
+        // Auto-register the kernel identity when any Kernel built-in is registered.
+        if (definition.kind === "Kernel.Abstract" && mod === "Kernel") {
+            this.identityMap.set("kernel", "Kernel");
+            this.reverseIdentityMap.set("Kernel", "kernel");
+        }
+        // If identity is already known, register the schema in AJV immediately.
+        if (mod && definition.schema) {
+            this.tryRegisterSchema(mod, name, definition.schema);
+        }
+    }
+    /** Register a module identity for x-telo-ref resolution.
+     *  Call once per Kernel.Module manifest when the manifest is loaded.
+     *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for kernel built-ins.
+     *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
+    registerModuleIdentity(namespace, moduleName) {
+        const identity = namespace ? `${namespace}/${moduleName}` : "kernel";
+        this.identityMap.set(identity, moduleName);
+        this.reverseIdentityMap.set(moduleName, identity);
+        // Retroactively register AJV schemas for definitions of this module already in the registry.
+        for (const def of this.defs.values()) {
+            if (def.metadata.module === moduleName && def.schema) {
+                this.tryRegisterSchema(moduleName, def.metadata.name, def.schema);
+            }
+        }
+    }
+    /** Computes the $id for a definition schema: "<identity>/<TypeName>".
+     *  Returns undefined when the module identity is not yet registered. */
+    computeId(moduleName, typeName) {
+        const identity = this.reverseIdentityMap.get(moduleName);
+        if (!identity)
+            return undefined;
+        return `${identity}/${typeName}`;
+    }
+    /** Validates data against a schema using this registry's AJV instance, which has all
+     *  registered definition schemas loaded — enabling cross-module $ref resolution. */
+    validateWithRefs(data, schema) {
+        let validate;
+        try {
+            validate = this.ajv.compile(schema);
+        }
+        catch {
+            return [];
+        }
+        if (validate(data))
+            return [];
+        return (validate.errors ?? []).map(formatSingleError);
+    }
+    tryRegisterSchema(moduleName, typeName, schema) {
+        const id = this.computeId(moduleName, typeName);
+        if (!id || this.registeredSchemaIds.has(id))
+            return;
+        if (this.ajv.getSchema(id)) {
+            throw new Error(`Duplicate definition schema $id: "${id}" is already registered`);
+        }
+        this.ajv.addSchema(schema, id);
+        this.registeredSchemaIds.add(id);
+    }
+    /** Resolves an x-telo-ref string to a canonical registry kind key.
+     *  Splits on "#", looks up the left side in the identity table, and returns
+     *  "<canonicalModule>.<TypeName>".
+     *
+     *  "kernel#Invocable"       → "Kernel.Invocable"
+     *  "std/pipeline#Job"       → "pipeline.Job"
+     *  "std/http-server#Server" → "http-server.Server"
+     *
+     *  Returns undefined when the string is malformed or the identity is not registered. */
+    resolveRef(xTeloRef) {
+        const hash = xTeloRef.indexOf("#");
+        if (hash === -1 || hash === xTeloRef.length - 1)
+            return undefined;
+        const identity = xTeloRef.slice(0, hash);
+        const typeName = xTeloRef.slice(hash + 1);
+        const moduleName = this.identityMap.get(identity);
+        if (!moduleName)
+            return undefined;
+        return `${moduleName}.${typeName}`;
+    }
+    resolve(kind) {
+        return this.defs.get(kind);
+    }
+    /** Returns the cached reference field map for the given kind, built once during register(). */
+    getFieldMap(kind) {
+        return this.fieldMaps.get(kind);
+    }
+    /** Returns the field map for `kind`, falling back to the alias-resolved kind when not found. */
+    getFieldMapForKind(kind, aliases) {
+        const fm = this.getFieldMap(kind);
+        if (fm)
+            return fm;
+        const resolved = aliases?.resolveKind(kind);
+        return resolved ? this.getFieldMap(resolved) : undefined;
+    }
+    /** Returns all definitions that transitively extend the given abstract kind.
+     *  Follows the capability chain to any depth (equivalent to instanceof in OOP).
+     *  Definitions are included regardless of registration order. */
+    getByExtends(abstractKind) {
+        const result = [];
+        const queue = [abstractKind];
+        while (queue.length > 0) {
+            const parent = queue.shift();
+            const children = this.extendedBy.get(parent);
+            if (!children)
+                continue;
+            for (const child of children) {
+                const def = this.defs.get(child);
+                if (def)
+                    result.push(def);
+                queue.push(child);
+            }
+        }
+        return result;
+    }
+    kinds() {
+        return Array.from(this.defs.keys());
+    }
+}

package/dist/dependency-graph.d.ts

@@ -0,0 +1,38 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+export interface ResourceNode {
+    kind: string;
+    name: string;
+}
+export interface DependencyGraph {
+    /** Topological order: each resource appears after all its dependencies (leaves first).
+     *  Present only when the graph is acyclic. */
+    order?: ReadonlyArray<ResourceNode>;
+    /** The cycle path when a circular dependency is detected.
+     *  The first and last elements are the same resource, tracing the full loop. */
+    cycle?: ReadonlyArray<ResourceNode>;
+}
+/**
+ * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
+ * returns either a topological initialization order or the cycle path.
+ *
+ * Edges represent boot-time dependencies only:
+ * - x-telo-ref fields that fall within a scope visibility path are excluded
+ *   (scoped resources are initialized on demand at runtime, not at boot).
+ * - x-telo-scope fields themselves are excluded from the graph.
+ *
+ * The registry is queried for each resource's field map by kind — callers do
+ * not pre-compute or pass field maps separately.
+ */
+export declare function buildDependencyGraph(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver): DependencyGraph;
+/**
+ * Formats a cycle result into a human-readable error string matching the spec:
+ *
+ *   Circular dependency detected:
+ *     Run.Sequence "DataSync"
+ *       → Http.Server "Api"
+ *       → Run.Sequence "DataSync"
+ */
+export declare function formatCycle(cycle: ReadonlyArray<ResourceNode>): string;
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,GACtB,eAAe,CAsFjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}

package/dist/dependency-graph.js

@@ -0,0 +1,155 @@
+import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+/** System resource kinds that are not runtime nodes in the dependency graph. */
+const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Import"]);
+const nodeKey = (kind, name) => `${kind}\0${name}`;
+/**
+ * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
+ * returns either a topological initialization order or the cycle path.
+ *
+ * Edges represent boot-time dependencies only:
+ * - x-telo-ref fields that fall within a scope visibility path are excluded
+ *   (scoped resources are initialized on demand at runtime, not at boot).
+ * - x-telo-scope fields themselves are excluded from the graph.
+ *
+ * The registry is queried for each resource's field map by kind — callers do
+ * not pre-compute or pass field maps separately.
+ */
+export function buildDependencyGraph(resources, registry, aliases) {
+    // --- Build node set ---
+    const nodes = new Map();
+    for (const r of resources) {
+        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const key = nodeKey(r.kind, r.metadata.name);
+        nodes.set(key, { kind: r.kind, name: r.metadata.name });
+    }
+    // --- Build adjacency: from → deps (from depends on dep) ---
+    const deps = new Map();
+    for (const key of nodes.keys())
+        deps.set(key, new Set());
+    for (const r of resources) {
+        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const sourceKey = nodeKey(r.kind, r.metadata.name);
+        const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
+        if (!fieldMap)
+            continue;
+        // Collect names of resources declared inside scope fields — these are initialized
+        // on-demand at runtime, not at boot, so edges pointing to them are excluded from the DAG.
+        const scopedNames = new Set();
+        for (const [scopeFieldPath, entry] of fieldMap) {
+            if (!isScopeEntry(entry))
+                continue;
+            const scopeVal = r[scopeFieldPath];
+            if (!Array.isArray(scopeVal))
+                continue;
+            for (const item of scopeVal) {
+                const name = item?.metadata?.name;
+                if (typeof name === "string")
+                    scopedNames.add(name);
+            }
+        }
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isRefEntry(entry))
+                continue;
+            for (const val of resolveFieldValues(r, fieldPath)) {
+                if (!val || typeof val !== "object")
+                    continue;
+                const ref = val;
+                if (!ref.kind || !ref.name)
+                    continue;
+                // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG
+                if (scopedNames.has(ref.name))
+                    continue;
+                const targetKey = nodeKey(ref.kind, ref.name);
+                if (nodes.has(targetKey)) {
+                    deps.get(sourceKey).add(targetKey);
+                }
+            }
+        }
+    }
+    // --- Kahn's topological sort ---
+    // in-degree[X] = number of X's dependencies (size of deps[X])
+    // reverse[dep] = set of nodes that depend on dep (for degree decrement)
+    const inDegree = new Map();
+    const reverse = new Map();
+    for (const key of nodes.keys()) {
+        inDegree.set(key, deps.get(key).size);
+        reverse.set(key, new Set());
+    }
+    for (const [from, depSet] of deps) {
+        for (const dep of depSet) {
+            reverse.get(dep)?.add(from);
+        }
+    }
+    const queue = [];
+    for (const [key, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(key);
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const key = queue.shift();
+        sorted.push(nodes.get(key));
+        for (const dependent of reverse.get(key)) {
+            const deg = inDegree.get(dependent) - 1;
+            inDegree.set(dependent, deg);
+            if (deg === 0)
+                queue.push(dependent);
+        }
+    }
+    if (sorted.length === nodes.size) {
+        return { order: sorted };
+    }
+    return { cycle: findCycle(nodes, deps) };
+}
+/**
+ * Formats a cycle result into a human-readable error string matching the spec:
+ *
+ *   Circular dependency detected:
+ *     Run.Sequence "DataSync"
+ *       → Http.Server "Api"
+ *       → Run.Sequence "DataSync"
+ */
+export function formatCycle(cycle) {
+    const lines = ["Circular dependency detected:"];
+    lines.push(`  ${cycle[0].kind} "${cycle[0].name}"`);
+    for (const node of cycle.slice(1)) {
+        lines.push(`    → ${node.kind} "${node.name}"`);
+    }
+    return lines.join("\n");
+}
+// --- Internals ---
+/** DFS cycle detection — returns the cycle path with the repeated start node appended. */
+function findCycle(nodes, deps) {
+    const state = new Map();
+    for (const key of nodes.keys())
+        state.set(key, "unvisited");
+    const stack = [];
+    function dfs(key) {
+        state.set(key, "visiting");
+        stack.push(key);
+        for (const dep of deps.get(key) ?? []) {
+            if (state.get(dep) === "visiting") {
+                const start = stack.indexOf(dep);
+                return [...stack.slice(start), dep];
+            }
+            if (state.get(dep) === "unvisited") {
+                const result = dfs(dep);
+                if (result)
+                    return result;
+            }
+        }
+        stack.pop();
+        state.set(key, "visited");
+        return null;
+    }
+    for (const key of nodes.keys()) {
+        if (state.get(key) === "unvisited") {
+            const result = dfs(key);
+            if (result)
+                return result.map((k) => nodes.get(k));
+        }
+    }
+    return [];
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { HttpAdapter } from "./adapters/http-adapter.js";
+export { createNodeAdapter, NodeAdapter } from "./adapters/node-adapter.js";
+export { RegistryAdapter } from "./adapters/registry-adapter.js";
+export { AnalysisRegistry } from "./analysis-registry.js";
+export { StaticAnalyzer } from "./analyzer.js";
+export { Loader } from "./manifest-loader.js";
+export { DiagnosticSeverity } from "./types.js";
+export type { AnalysisDiagnostic, AnalysisOptions, LoadOptions, ManifestAdapter, Position, PositionIndex, Range } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,eAAe,EACf,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { HttpAdapter } from "./adapters/http-adapter.js";
+export { createNodeAdapter, NodeAdapter } from "./adapters/node-adapter.js";
+export { RegistryAdapter } from "./adapters/registry-adapter.js";
+export { AnalysisRegistry } from "./analysis-registry.js";
+export { StaticAnalyzer } from "./analyzer.js";
+export { Loader } from "./manifest-loader.js";
+export { DiagnosticSeverity } from "./types.js";

package/dist/manifest-loader.d.ts

@@ -0,0 +1,11 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { LoadOptions, ManifestAdapter } from "./types.js";
+export declare class Loader {
+    protected adapters: ManifestAdapter[];
+    constructor(extraAdapters?: ManifestAdapter[]);
+    register(adapter: ManifestAdapter): this;
+    private pick;
+    loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]>;
+    loadManifests(entryUrl: string): Promise<ResourceManifest[]>;
+}
+//# sourceMappingURL=manifest-loader.d.ts.map

package/dist/manifest-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAA2B,MAAM,YAAY,CAAC;AAExF,qBAAa,MAAM;IACjB,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,CAA8C;gBAEvE,aAAa,GAAE,eAAe,EAAO;IAIjD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAKxC,OAAO,CAAC,IAAI;IAMN,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgE3E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAwCnE"}