See ConstructTreeDiagramResult.
const diagram = await constructTreeDiagram({ actionID: "aid-1234", ansi: true });
console.log(diagram);
commit-robbery [a1]
└─ get-sentenced [a2]
└─ meet-in-yard [a3]
└─ * scheme-together [a4]
└─ attempt-escape [a5]
├─ flee-country [a6] → cross-border [a7] → reach-safehouse [a8]
└─ launch-manhunt [a9] → set-up-roadblocks [a10]
commit-fraud [b1]
└─ get-sentenced [b2]
└─ meet-in-yard [=a3]
┌────────────────────────┐
│ a1 : aid-9f2a3b7c │
│ a2 : aid-4d8e1f3a │
│ a3 : aid-7b2c9d4e │
│ *a4 : aid-1234 │
│ a5 : aid-6c3d7a9b │
│ a6 : aid-8e4f2a1c │
│ a7 : aid-3b9d6e5f │
│ a8 : aid-5a1c8d2e │
│ a9 : aid-2f7b4a3d │
│ a10 : aid-9d3e6f1a │
│ b1 : aid-4a8b2c7d │
│ b2 : aid-7f1d5e9a │
└────────────────────────┘
VivNotInitializedError If Viv has not been initialized.
VivValidationError If actionID is not a valid entity ID for an action.
Returns a causal tree diagram that is anchored in a given action, displaying the entire causal structure rooted in the action's causal primogenitor(s).
This diagram will include every action that is causally related to the given one, either as an ancestor, a descendant, or a collateral relative. Rather than a tree, the diagram will technically be structured as a directed acyclic graph (DAG), the roots of which are all the actions that are causally related to the given one and have no direct causes. The leaves will be actions that caused no other actions. Multiple roots obtain when the anchor (or an ancestor) is directly caused by actions from two or more lineages that do not share a common ancestor.
As a concrete example, imagine a story about a prison escape, where two inmates scheme together to devise a clever escape plan, which succeeds. In a Viv-powered simulation, the two inmates might have each been sent to prison as a result of distinct complex emergent storylines that are themselves causal trees.
When the characters decide to scheme together, that action could have both of the backstory trees as causal lineages, meaning the two trees converged into one node. And as the escape plays out, with its own upshot and ramifications, those downstream emergent storylines would themselves be trees that are components of the larger one at play here. So multiple trees converge on one node, and that node then spawns multiple distinct trees downstream from it.
In any reasonably complex Viv project, and particularly ones that make proper use of reactions, these trees can resemble a hyper-Pynchonian gnarl that challenges human interpretation -- but the tree will be made of smaller trees that correspond more directly to conventional storylines.
In the tree diagram, each node is identified in a compact notation combining a family-letter prefix with a numeric identifier. The family-letter prefix corresponds to one of the root actions in the tree (DAG). While an action node can of course have multiple root ancestors, it will be associated with the one in whose subtree it first appears. Later references to the same action will reuse that same identifier, in a back reference (see below).
Here's a breakdown on the notation used in the diagrams:
<family-letter><number>.*).→-separated runs.[=identifier]are used for actions that have already appeared in the diagram, above where the back reference is used.