Dependency flattening
How one template version's dependency tree becomes one ordered list of template versions to run, and why the order is what it is.
Dependency flattening turns a template version and everything it depends on into one list, in run order. Children come before parents, siblings run in order of their version id, and the root runs last. It never picks a version: every dependency is already a fixed version id, pinned by the registry at push.
How it works
Input: a tree of pinned version ids
- A template version lists its dependencies as
templatesrefs. Each ref holds a version id (a GUID), a version number, and optional preset answers. Evidence:TemplateVersionTemplateRefResinsulfone.iridium/cyanregistry/src/http/models/template_res.rs:55-59; the GUID comes fromTemplateVersionTemplateRefResp(Guid Id, ...)insulfone.zinc/App/Modules/Cyan/API/V1/Models/TemplateVersionModel.cs:103. - The version id is fixed when the parent is pushed, not at run time. See reference pinning.
The walk
flatten_impl (resolver.rs:63-117) is a depth-first walk that writes into one shared list:
- Sort the children by version id (
resolver.rs:70-71). - For each child:
- Already in the list? (
resolver.rs:86-94) Merge its preset answers into the entry that is there. A key that is already set keeps its value (or_insert, line 91). Do not walk it again. - Already seen on this walk? (
resolver.rs:97-99) Skip it. This stops cycles. - Otherwise: fetch the child by version id (line 102), mark it seen, walk its children first (line 107), then append the child (line 110). This is post-order.
- Already in the list? (
- Append the root last, with no preset answers (
resolver.rs:179-186). The root is marked seen before the walk (line 179), so a cycle back to the root never adds it twice.
What the list is used for
The composition operator runs the list in order (operator.rs:240).
The list index of each entry is its layer in dependency layering (operator.rs:151-161).
A later layer wins a file clash when no resolver settles it.
Worked example
atomi/web version 5 has this cyan.yaml:
templates:- atomi/node-base:3- template: atomi/dockerpreset_answers:port: "8080"
When atomi/web:5 was pushed, the registry pinned atomi/docker to its latest version then, version 7.
atomi/node-base:3 depends on atomi/lint:2. atomi/docker:7 also depends on atomi/lint:2, with preset strict: true.
| Template version | Version id (shortened) |
|---|---|
atomi/web:5 | e0… |
atomi/docker:7 | 4f… |
atomi/node-base:3 | c1… |
atomi/lint:2 | 9a… |
The walk:
- Children of
web:5, sorted by id:docker:7(4f…), thennode-base:3(c1…). docker:7: walk its childlint:2, appendlint:2withstrict: true, then appenddocker:7withport: "8080".node-base:3: its childlint:2is already in the list. Its preset answers merge in;strictkeepstrue. Appendnode-base:3.- Append
web:5.
Run order and layers:
| Layer | Template version | Preset answers |
|---|---|---|
| 0 | atomi/lint:2 | strict: true |
| 1 | atomi/docker:7 | port: "8080" |
| 2 | atomi/node-base:3 | none |
| 3 | atomi/web:5 | none |
Note: docker runs before node-base although cyan.yaml lists node-base first. The order comes from the version ids, not from cyan.yaml.
Rules worth knowing
- Run order is not the
cyan.yamlorder. Siblings run in version-id order (resolver.rs:71). A template author cannot choose which sibling wins a file clash. - The same template at two versions runs twice. Dedup is by version id (
resolver.rs:88), solint:2andlint:3are two entries. - The first preset answer for a key wins. A later branch only fills keys that are still empty (
resolver.rs:91). - Only string, boolean and string-list presets survive. Any other JSON value is dropped (
resolver.rs:18-35). - A template group has no image of its own. It stays in the list but is skipped when the list runs (
operator.rs:244-257).
Why this way
- Same order on every run. The code sorts children by id "to ensure deterministic execution order" (
resolver.rs:69). A fixed order is what lets an update rebuild the same base files (see three-way merge). - Children before parents, root last. Inferred: in layering a later layer wins, so a parent's files land on top of its children's, and the root has the final word.
- No version choice at run time. Pins are made once at push, so a project always rebuilds the exact tree it was made from.