@telorun/analyzer 0.53.0 → 0.55.0

package/dist/call-graph.js

@@ -0,0 +1,617 @@
+import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import { enclosingOf, propertySchemas, resolveLocalRef, } from "./manifest-navigation.js";
+import { visitManifest } from "./manifest-visitor.js";
+import { possibleUses, readRefSlot, transfersControl, } from "./ref-slot.js";
+import { isRefEntry, resolveFieldEntries } from "./reference-field-map.js";
+import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+export const resourceId = (kind, name) => `${kind}\0${name}`;
+/**
+ * Does control reach this edge's target?
+ *
+ * An edge whose slot declares NO use — the bare-string form, still accepted
+ * while the ecosystem migrates, and every value-tree-discovered ref — counts as
+ * control-transferring. That is the conservative direction for every consumer
+ * of this predicate: the cost of a false "control reaches here" is a check that
+ * stays silent, while the cost of a false "it never does" is a valid manifest
+ * rejected. It is also exactly what the walkers this replaced did, so an
+ * unannotated third-party kind behaves as it did before. The branch disappears
+ * when `use` becomes mandatory.
+ */
+function reachesTarget(edge) {
+    return edge.use.length === 0 || edge.use.some(transfersControl);
+}
+/** Navigate a JSON Pointer relative to the object enclosing the annotated slot.
+ *
+ *  One rule serves a resource-level sibling and an array item's sibling, and
+ *  nothing can address across an array boundary — if a case for root anchoring
+ *  ever appears it gets its own spelling, the split `x-telo-context-from` /
+ *  `x-telo-context-from-root` already make. */
+function navigatePointer(enclosing, pointer) {
+    if (!pointer.startsWith("/"))
+        return undefined;
+    let current = enclosing;
+    for (const rawSegment of pointer.slice(1).split("/")) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+        current = Array.isArray(current)
+            ? current[Number(segment)]
+            : current[segment];
+    }
+    return current;
+}
+const NO_DEFAULT = () => undefined;
+/** Schema-declared `default:` for a selector pointer, resolved against the
+ *  schema of the object ENCLOSING the annotated slot — the same anchoring the
+ *  runtime value walk uses. This is what classifies the common spelling: a
+ *  `Lease.Critical` that omits `detach:` takes the schema's `default: false`
+ *  and is a `call` edge, not an unresolved one. */
+function schemaDefaultOf(enclosingSchema) {
+    if (!enclosingSchema)
+        return NO_DEFAULT;
+    return (pointer) => {
+        if (!pointer.startsWith("/"))
+            return undefined;
+        let current = enclosingSchema;
+        let value;
+        for (const rawSegment of pointer.slice(1).split("/")) {
+            if (!current)
+                return undefined;
+            const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+            const next = propertySchemas(current).find(([k]) => k === segment)?.[1];
+            if (!next)
+                return undefined;
+            value = next.default;
+            current = next;
+        }
+        return value;
+    };
+}
+/** The schema node describing the object that ENCLOSES a slot, from the slot's
+ *  field-map path (`routes[].handler` → `routes`' item schema). Follows `[]`
+ *  into `items` and `{}` into `additionalProperties`, resolving local `$ref`s. */
+function enclosingSchemaOf(rootSchema, slotFieldPath) {
+    const segments = slotFieldPath.split(".");
+    segments.pop(); // the slot itself — we want its parent object
+    let current = rootSchema;
+    for (const segment of segments) {
+        if (!current)
+            return undefined;
+        const bare = segment.replace(/(\[\]|\{\})+$/g, "");
+        let next = propertySchemas(current).find(([k]) => k === bare)?.[1];
+        if (!next)
+            return undefined;
+        for (const marker of segment.slice(bare.length).match(/\[\]|\{\}/g) ?? []) {
+            next =
+                marker === "[]"
+                    ? next?.items
+                    : next?.additionalProperties;
+            next = resolveLocalRef(next, rootSchema);
+            if (!next || typeof next !== "object")
+                return undefined;
+        }
+        current = resolveLocalRef(next, rootSchema);
+    }
+    return current;
+}
+/**
+ * Resolve a slot's declared use at one concrete site.
+ *
+ * A case map's selector must be statically resolvable — a literal or a schema
+ * default. There is deliberately no fallback: no single value is conservative
+ * for every consumer, since the throws union must assume `call` to keep an error
+ * path and a zone requirement must assume the opposite to avoid inventing one.
+ * When the selector cannot be read the edge reports every case's use AND says
+ * why (`unresolvedReason`), so a consumer chooses its own reading — and
+ * `validate-ref-slots.ts` turns the `dynamic` reason into a diagnostic, because
+ * a call graph known only at runtime is not statically analyzable.
+ */
+function resolveUseAtSite(entry, root, concretePath, schemaDefault) {
+    if (!entry.useCases)
+        return { use: entry.uses };
+    const enclosing = enclosingOf(root, concretePath);
+    let selector = navigatePointer(enclosing, entry.useCases.by);
+    if (selector === undefined)
+        selector = schemaDefault(entry.useCases.by);
+    if (selector !== undefined && typeof selector !== "object") {
+        const resolved = entry.useCases.cases[String(selector)];
+        if (resolved)
+            return { use: resolved };
+    }
+    const slot = { kinds: entry.refs, uses: entry.uses, useCases: entry.useCases, inline: false };
+    const unresolvedReason = isTaggedSentinel(selector)
+        ? "dynamic"
+        : selector === undefined
+            ? "absent"
+            : "unmatched";
+    return { use: possibleUses(slot), unresolved: entry.useCases, unresolvedReason };
+}
+/** Names the step-list annotation on an array property, if any. */
+function stepContextOf(schema) {
+    const annotation = schema?.["x-telo-step-context"];
+    return annotation && typeof annotation === "object" ? annotation : undefined;
+}
+/** A resolved plain reference value (`{kind, name}`, optionally `alias`) — the
+ *  shape `resolveRefSentinels` leaves at a ref site. NOT a step: a bare boot
+ *  target written `!ref X` must not mint a step node. */
+function isPlainRefValue(value) {
+    if (typeof value.kind !== "string" || typeof value.name !== "string")
+        return false;
+    return Object.keys(value).every((k) => k === "kind" || k === "name" || k === "alias" || k === "__ref");
+}
+/**
+ * Emit the edges a single step's own ref slots declare.
+ *
+ * Read from the step ITEM SCHEMA rather than from the reference field map: a
+ * step array's items sit behind a local `$ref`, and the field map deliberately
+ * does not descend one (descending it there would turn every step's `invoke`
+ * into a Phase-5 injection site). The schema is already in hand here, so the
+ * graph sees these slots at no cost to the kernel's injection surface.
+ */
+function emitStepEdges(node, ctx) {
+    if (!ctx.itemSchema)
+        return;
+    const schemaDefault = schemaDefaultOf(ctx.itemSchema);
+    for (const [key, propSchema] of propertySchemas(ctx.itemSchema)) {
+        const slot = readRefSlot(propSchema);
+        if (!slot || slot.kinds.length === 0)
+            continue;
+        const targetName = refTargetName(node.step[key]);
+        if (targetName === undefined)
+            continue;
+        const entry = {
+            refs: slot.kinds,
+            uses: slot.uses,
+            isArray: false,
+            ...(slot.useCases ? { useCases: slot.useCases } : {}),
+            ...(slot.inputs !== undefined ? { inputs: slot.inputs } : {}),
+        };
+        // The step itself is the enclosing object, so a `use` case map and an
+        // `inputs` pointer both resolve against the step's own siblings.
+        const { use, unresolved, unresolvedReason } = resolveUseAtSite(entry, node.step, key, schemaDefault);
+        const edge = {
+            from: node.id,
+            toName: targetName,
+            slot: `${ctx.slotPrefix}.${key}`,
+            path: `${node.path}.${key}`,
+            use,
+        };
+        const target = ctx.resolveName(targetName);
+        if (target)
+            edge.to = target.id;
+        if (unresolved)
+            edge.unresolved = unresolved;
+        if (unresolvedReason)
+            edge.unresolvedReason = unresolvedReason;
+        if (slot.inputs !== undefined)
+            edge.inputs = slot.inputs;
+        ctx.edges.push(edge);
+        ctx.stepEdgesByPath.set(`${node.owner}\0${edge.path}`, edge);
+    }
+}
+/**
+ * The single step-array recursion in the analyzer.
+ *
+ * A step's position is manifest data, never schema data: no definition declares
+ * a next or previous step, and none needs to — order is the written order of the
+ * array, and this is a manifest × schema co-traversal, so the array is in hand
+ * exactly where step nodes are minted. The schema's whole contribution is to
+ * mark an array as a step list and to name the fields that nest further steps
+ * (`branch`, `branch-list`, `case-map`).
+ */
+function walkSteps(steps, arrayPath, parent, ctx) {
+    const dispatchRole = (data, role, itemsSchema, path, stepId) => {
+        if (role === "branch" && Array.isArray(data)) {
+            walkSteps(data, path, stepId, ctx);
+        }
+        else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+            for (const [caseKey, arr] of Object.entries(data)) {
+                if (Array.isArray(arr))
+                    walkSteps(arr, `${path}.${caseKey}`, stepId, ctx);
+            }
+        }
+        else if (role === "branch-list" && Array.isArray(data)) {
+            const entrySchema = resolveLocalRef(itemsSchema, ctx.rootSchema);
+            if (!entrySchema)
+                return;
+            data.forEach((entry, i) => {
+                if (!entry || typeof entry !== "object")
+                    return;
+                for (const [subKey, subSchema] of propertySchemas(entrySchema)) {
+                    const subRole = subSchema["x-telo-topology-role"];
+                    if (typeof subRole !== "string")
+                        continue;
+                    dispatchRole(entry[subKey], subRole, subSchema.items, `${path}[${i}].${subKey}`, stepId);
+                }
+            });
+        }
+    };
+    steps.forEach((step, index) => {
+        if (!step || typeof step !== "object" || Array.isArray(step))
+            return;
+        // A bare reference in a step position (`targets: [!ref X]`, or the resolved
+        // `{kind, name}` it becomes) is a target, not a step — the field-map walk
+        // owns that edge. Minting a node here would put ref noise in the step model.
+        if (isRefSentinel(step))
+            return;
+        const value = step;
+        if (isPlainRefValue(value))
+            return;
+        const path = `${arrayPath}[${index}]`;
+        const id = `${ctx.owner.id}#${path}`;
+        const node = {
+            type: "step",
+            id,
+            owner: ctx.owner.id,
+            path,
+            array: arrayPath,
+            index,
+            step: value,
+        };
+        if (typeof value.name === "string")
+            node.name = value.name;
+        if (parent)
+            node.parent = parent;
+        ctx.nodes.set(id, node);
+        ctx.order.push(node);
+        emitStepEdges(node, ctx);
+        if (!ctx.itemSchema)
+            return;
+        for (const [key, propSchema] of propertySchemas(ctx.itemSchema)) {
+            const role = propSchema["x-telo-topology-role"];
+            if (typeof role !== "string")
+                continue;
+            dispatchRole(value[key], role, propSchema.items, `${path}.${key}`, id);
+        }
+    });
+}
+/** The concrete step path a nested site belongs to, or undefined for a
+ *  resource-level site. Longest-prefix match, so a site inside `steps[0].do[1]`
+ *  attaches to that step rather than to `steps[0]`. */
+function ownerStepOf(steps, concretePath) {
+    let best;
+    for (const step of steps) {
+        if (!concretePath.startsWith(`${step.path}.`))
+            continue;
+        if (!best || step.path.length > best.path.length)
+            best = step;
+    }
+    return best;
+}
+/**
+ * Build the call graph for one manifest set.
+ *
+ * Reference discovery is three-fold. Field-map sites come from `visitManifest`
+ * — the same walk the reference validators use — and are stamped `injected`,
+ * because those and only those are Phase-5 injection sites. Step slots are read
+ * from the step item schema, because they sit behind local `$ref`s the field
+ * map deliberately does not descend. Everything else is caught by the value-
+ * tree scan (`discoverNestedRefs`): a `!ref` is an explicit marker, so a ref in
+ * a structure no annotation anticipated is still an edge — with no declared
+ * `use`, read conservatively — instead of a blind spot. Inline declarations in
+ * `x-telo-scope` arrays become scoped nodes with edges of their own.
+ */
+export function buildCallGraph(resources, registry, options = {}) {
+    const nodes = new Map();
+    const edges = [];
+    const byName = new Map();
+    const stepsByOwner = new Map();
+    const stepEdgesByPath = new Map();
+    /**
+     * A resource's definition, resolved in the scope of the module that DECLARED
+     * it. A manifest carries the kind as AUTHORED (`Run.Sequence`), while the
+     * registry is keyed canonically (`run.Sequence`), so a raw lookup misses for
+     * every alias-form kind — which is every kind in a real manifest. That miss
+     * is silent and costly: step collection would find no step list (so a step's
+     * declared `use` never reaches its edge, and the site degrades to an untyped
+     * value-tree edge), and a case map's selector would find no schema `default`
+     * (so a slot resolved by an omitted field reads as unresolved). Same scope
+     * selection as `expandedFieldMapForResource`.
+     */
+    const definitionFor = (manifest) => {
+        const direct = registry.resolve(manifest.kind);
+        if (direct)
+            return direct;
+        const module = manifest.metadata?.module;
+        const scope = (module ? options.aliasesByModule?.get(module) : undefined) ?? options.aliases;
+        const canonical = scope?.resolveKind(manifest.kind);
+        return canonical ? registry.resolve(canonical) : undefined;
+    };
+    for (const manifest of resources) {
+        const name = manifest.metadata?.name;
+        if (!name || !manifest.kind || SYSTEM_KINDS.has(manifest.kind))
+            continue;
+        const node = {
+            type: "resource",
+            id: resourceId(manifest.kind, name),
+            kind: manifest.kind,
+            name: name,
+            manifest,
+        };
+        nodes.set(node.id, node);
+        byName.set(node.name, node);
+    }
+    // --- step nodes ---
+    const collectStepsFor = (node, resolveName) => {
+        const definition = definitionFor(node.manifest);
+        const schema = definition?.schema;
+        if (!schema)
+            return;
+        const collected = [];
+        for (const [key, propSchema] of propertySchemas(schema)) {
+            const annotation = stepContextOf(propSchema);
+            if (!annotation)
+                continue;
+            const value = node.manifest[key];
+            if (!Array.isArray(value))
+                continue;
+            walkSteps(value, key, undefined, {
+                owner: node,
+                rootSchema: schema,
+                itemSchema: resolveLocalRef(propSchema.items, schema),
+                slotPrefix: `${key}[]`,
+                nodes,
+                order: collected,
+                resolveName,
+                edges,
+                stepEdgesByPath,
+            });
+        }
+        if (collected.length > 0)
+            stepsByOwner.set(node.id, collected);
+    };
+    for (const node of [...nodes.values()]) {
+        collectStepsFor(node, (name) => byName.get(name));
+    }
+    // --- edges ---
+    // Scope-local nodes of the CURRENT resource. The visitor fires `onScope`
+    // before that resource's ref sites, so both are set before any edge they
+    // qualify is added. Scope-local names win over module-level ones — the order
+    // `ScopeContext` and `!ref` already agree on.
+    let scopedNames = new Set();
+    let scopeLocal = new Map();
+    const fieldMapFor = (manifest) => {
+        if (options.aliases && options.aliasesByModule) {
+            return registry.expandedFieldMapForResource(manifest, options.aliases, options.aliasesByModule);
+        }
+        if (options.aliases)
+            return registry.getFieldMapForKind(manifest.kind, options.aliases);
+        return registry.getFieldMap(manifest.kind);
+    };
+    visitManifest(resources, registry, {
+        onScope: (event) => {
+            scopedNames = event.enclosedNames;
+            scopeLocal = new Map();
+            const ownerName = event.source.metadata?.name;
+            if (!ownerName || !event.source.kind)
+                return;
+            const ownerId = resourceId(event.source.kind, ownerName);
+            // Inline declarations inside `x-telo-scope` arrays become nodes of
+            // their own, keyed by their scope site — the declaration-site identity
+            // the zones plan correlates on. They are excluded from init ordering
+            // (created when the scope opens), but their own references are real
+            // edges of the one model.
+            for (const [pointer, manifests] of event.manifestsByPointer) {
+                for (const manifest of manifests) {
+                    const name = manifest.metadata?.name;
+                    if (typeof name !== "string" || !manifest.kind)
+                        continue;
+                    const scopedNode = {
+                        type: "resource",
+                        id: `${ownerId}#${pointer}#${resourceId(manifest.kind, name)}`,
+                        kind: manifest.kind,
+                        name,
+                        manifest,
+                        scoped: true,
+                        scopeOwner: ownerId,
+                        scopeSite: pointer,
+                    };
+                    nodes.set(scopedNode.id, scopedNode);
+                    scopeLocal.set(name, scopedNode);
+                }
+            }
+            if (scopeLocal.size === 0)
+                return;
+            const resolveScoped = (name) => scopeLocal.get(name) ?? byName.get(name);
+            // The owner's own step edges were emitted before this scope was seen
+            // (step collection precedes the visit), so their names resolved
+            // module-level. Re-resolve them now that the scope exists: scope-local
+            // names WIN — the order `ScopeContext` and `!ref` already agree on — so
+            // a step's `invoke: !ref X` with X declared in `with:` reaches the
+            // scoped node, never a same-named module-level shadow.
+            for (const [key, edge] of stepEdgesByPath) {
+                if (!key.startsWith(`${ownerId}\0`))
+                    continue;
+                const local = scopeLocal.get(edge.toName);
+                if (!local)
+                    continue;
+                edge.to = local.id;
+                edge.scoped = true;
+            }
+            for (const scopedNode of scopeLocal.values()) {
+                // The scoped resource's own ref slots, from its kind's field map.
+                const fieldMap = fieldMapFor(scopedNode.manifest);
+                if (fieldMap) {
+                    const definition = definitionFor(scopedNode.manifest);
+                    const rootSchema = definition?.schema;
+                    for (const [fieldPath, entry] of fieldMap) {
+                        if (!isRefEntry(entry))
+                            continue;
+                        for (const { value, path } of resolveFieldEntries(scopedNode.manifest, fieldPath)) {
+                            const targetName = refTargetName(value);
+                            if (targetName === undefined)
+                                continue;
+                            const schemaDefault = rootSchema
+                                ? schemaDefaultOf(enclosingSchemaOf(rootSchema, fieldPath))
+                                : NO_DEFAULT;
+                            const { use, unresolved, unresolvedReason } = resolveUseAtSite(entry, scopedNode.manifest, path, schemaDefault);
+                            const edge = {
+                                from: scopedNode.id,
+                                toName: targetName,
+                                slot: fieldPath,
+                                path,
+                                use,
+                            };
+                            const target = resolveScoped(targetName);
+                            if (target)
+                                edge.to = target.id;
+                            if (unresolved)
+                                edge.unresolved = unresolved;
+                            if (unresolvedReason)
+                                edge.unresolvedReason = unresolvedReason;
+                            if (entry.inputs !== undefined)
+                                edge.inputs = entry.inputs;
+                            edges.push(edge);
+                        }
+                    }
+                }
+                // Its step arrays too, resolved scope-local first.
+                collectStepsFor(scopedNode, resolveScoped);
+            }
+        },
+        onRef: (event) => {
+            const sourceName = event.source.metadata?.name;
+            if (!sourceName || !event.source.kind)
+                return;
+            const sourceId = resourceId(event.source.kind, sourceName);
+            if (!nodes.has(sourceId))
+                return;
+            // A site inside a step was already emitted by the step walk, which
+            // reads the step item schema directly. When the FIELD MAP also reaches
+            // it — `Telo.Application`'s inline `targets[].invoke`, unlike
+            // `Run.Sequence`'s `$ref`-hidden `steps[].invoke` — the site is a
+            // Phase-5 injection site, and the existing step edge is stamped so the
+            // init-order projection keeps it.
+            if (ownerStepOf(stepsByOwner.get(sourceId) ?? [], event.concretePath)) {
+                if (!event.nested) {
+                    const stepEdge = stepEdgesByPath.get(`${sourceId}\0${event.concretePath}`);
+                    if (stepEdge)
+                        stepEdge.injected = true;
+                }
+                return;
+            }
+            const targetName = refTargetName(event.value);
+            if (targetName === undefined)
+                return;
+            const definition = definitionFor(event.source);
+            const rootSchema = definition?.schema;
+            const schemaDefault = !event.nested && rootSchema
+                ? schemaDefaultOf(enclosingSchemaOf(rootSchema, event.fieldPath))
+                : NO_DEFAULT;
+            const { use, unresolved, unresolvedReason } = resolveUseAtSite(event.entry, event.source, event.concretePath, schemaDefault);
+            const edge = {
+                from: sourceId,
+                toName: targetName,
+                slot: event.fieldPath,
+                path: event.concretePath,
+                use,
+            };
+            const target = scopedNames.has(targetName)
+                ? (scopeLocal.get(targetName) ?? byName.get(targetName))
+                : byName.get(targetName);
+            if (target)
+                edge.to = target.id;
+            if (unresolved)
+                edge.unresolved = unresolved;
+            if (unresolvedReason)
+                edge.unresolvedReason = unresolvedReason;
+            if (event.entry.inputs !== undefined)
+                edge.inputs = event.entry.inputs;
+            if (event.nested)
+                edge.nested = true;
+            else
+                edge.injected = true;
+            if (scopedNames.has(targetName))
+                edge.scoped = true;
+            edges.push(edge);
+        },
+    }, {
+        aliases: options.aliases,
+        aliasesByModule: options.aliasesByModule,
+        skipKinds: SYSTEM_KINDS,
+        expand: true,
+        discoverNestedRefs: true,
+    });
+    const fromIndex = new Map();
+    const toIndex = new Map();
+    const push = (index, key, edge) => {
+        const bucket = index.get(key);
+        if (bucket)
+            bucket.push(edge);
+        else
+            index.set(key, [edge]);
+    };
+    for (const edge of edges) {
+        push(fromIndex, edge.from, edge);
+        if (edge.to)
+            push(toIndex, edge.to, edge);
+    }
+    return {
+        nodes,
+        edges,
+        edgesFrom: (id) => fromIndex.get(id) ?? [],
+        edgesTo: (id) => toIndex.get(id) ?? [],
+        resource: (kind, name) => nodes.get(resourceId(kind, name)),
+        resourceByName: (name) => byName.get(name),
+        steps: (ownerId) => stepsByOwner.get(ownerId) ?? [],
+        controlEdges: () => edges.filter(reachesTarget),
+    };
+}
+/** The target resource NAME a ref site's value carries. Both written forms reach
+ *  here: an unresolved `!ref <name>` sentinel and the `{kind, name}` object
+ *  `resolveRefSentinels` rewrites it into. */
+function refTargetName(value) {
+    if (isRefSentinel(value))
+        return value.source;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const name = value.name;
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * Unique `(from, to)` pairs, dropping slot identity and `use`. The projection
+ * the init-order consumer needs — the only consumer for which the distinction
+ * between two parallel edges genuinely does not matter.
+ *
+ * **Only injection sites order boot, and that is a property of the SITE, never
+ * of the node kind.** A site the reference field map reaches is a Phase-5
+ * injection site: the kernel puts the live instance into the field before
+ * `init()`, so the target must be constructed first — and that is as true for
+ * `Telo.Application`'s inline `targets[].invoke` (a step-declared slot the
+ * field map reaches) as for a resource-level `connection:`. A step slot behind
+ * a local `$ref` and a value-tree-discovered ref resolve at dispatch instead,
+ * so their targets need only exist by the time the step runs. An earlier
+ * revision keyed this on node kind and silently dropped boot targets' inline
+ * invoke edges from init order — the regression this comment exists to prevent.
+ *
+ * Scoped nodes take no part at all: a `with:`-scoped resource is created when
+ * the scope opens, and an edge into a scope is the owner's runtime business.
+ */
+export function projectToPairs(graph, options = {}) {
+    const out = new Map();
+    for (const [id, node] of graph.nodes) {
+        if (node.type === "resource" && !node.scoped)
+            out.set(id, new Set());
+    }
+    for (const edge of graph.edges) {
+        if (!edge.to)
+            continue;
+        if (!edge.injected && !options.includeNonInjected)
+            continue;
+        if (options.keepUse && !options.keepUse(edge.use))
+            continue;
+        const from = graph.nodes.get(edge.from);
+        const to = graph.nodes.get(edge.to);
+        if (to?.type === "resource" && to.scoped)
+            continue;
+        let ownerId;
+        if (from?.type === "step")
+            ownerId = from.owner;
+        else if (from?.type === "resource" && from.scoped)
+            continue;
+        else
+            ownerId = edge.from;
+        out.get(ownerId)?.add(edge.to);
+    }
+    return out;
+}

package/dist/dependency-graph.d.ts

@@ -14,16 +14,26 @@ export interface DependencyGraph {
     cycle?: ReadonlyArray<ResourceNode>;
 }
 /**
- * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
+ * Builds a directed acyclic graph (DAG) of boot-time 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.
+ * A projection of the typed reference graph, not a second walk of the manifest.
+ * What this consumer keeps of the full graph:
  *
- * The registry is queried for each resource's field map by kind — callers do
- * not pre-compute or pass field maps separately.
+ * - **Injection sites only.** A site the reference field map reaches is a
+ *   Phase-5 injection site, so its target must be constructed first — including
+ *   `Telo.Application`'s inline `targets[].invoke`, which is step-declared but
+ *   injected. A step slot behind a local `$ref` and a value-tree-discovered ref
+ *   resolve at dispatch, so their targets need only exist by the time the step
+ *   runs. All can be `use: call` — the difference is the site, never the node
+ *   kind or the use.
+ * - **Every use but `schema`.** A `Telo.Type` slot names a shape; no runtime
+ *   instance is constructed, so there is nothing to order against.
+ * - **No edge into the source's own scope.** A scoped resource is created when
+ *   the scope opens, not at boot.
+ * - **Pairs, not parallel edges.** This is the one consumer for which two slots
+ *   naming the same target genuinely mean the same thing, so it collapses the
+ *   multigraph itself instead of the graph erasing the distinction for everyone.
  */
 export declare function buildDependencyGraph(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): DependencyGraph;
 /**

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

@@ -1 +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;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE,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;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAmGjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}
+{"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;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,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;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAyDjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}