Historical Modeling with Factually

Dot Graph

Legend

The following Fact Type prefixes provide additional definition to the type without the need to include additional types or fields in order to fully define the type.

@ - time-based (moment)
# - grant/revoke
$ - singleton fact
% - disable/enable
^ - irreversible disable
: - reversible delete
! - irreversible delete

Historical Modeling Overview

A Fact represents an irreversible declaration that something has happened. This makes Facts immutable which means they never change once created and successfully shared with others.

An Historical Model describes the relationships between different types of Facts. The immutable nature of such a model allows distributed nodes to remain autonomous in creating new Facts, while providing a common data substrate that all nodes can share.

A Fact may or may not have Predecessors. Predecessors to a fact may be optional (zero or 1), required (must have 1 and only 1), or multiple (zero to many, also known as fact capturing). Since Facts are immutable, once a Fact has been created, its Predecessors can never change.

A Fact may or may not have Successors. From the perspective of cause-and-effect, a Successor always comes after a Predecessor. Therefore, Successors can always be added to a Fact.

Sometimes things do need to change over time. An Historical Model simulates mutability by describing Successor Facts that link together in a self-referencing chain. The first Fact in this chain has no prior Fact. Each Succeeding Fact references the last Fact in the current chain as prior to it. The "current" Fact is represented by the Fact in the chain that no other Fact of the same type references as prior.

Historical Modeling begins by defining facts and the relationships between them in a visual graph of nodes and arrows. Some additional constraints for this form of modeling are:

Lines always point up from a Successor to a Predecessor.
Required Predecessors are represented with an arrow from Successor to Predecessor. Multiple Successors are modeled in the same fashion.
Optional Predecessors are represented with an arrow plus a question mark (?).
Multiple Predecessors are represented with an arrow plus an asterisk (*).
A "mutable" Successor is represented with an arrow to its Predecessor, and a self-referencing arrow to itself plus an asterisk (*).

You can find out more about Historical Modeling in The Art of Immutable Architecture. Theory and Practice of Data Management in Distrubuted Systems by Michael L. Perry. Apress, 2020. ISBN 978-1-4842-5954-2.

Example Fact Instances

{
  "facts": [
    {
      "id": "e5778396-5391-404a-8175-5e71d57c259c",
      "type": "OptionalPredecessor"
    },
    {
      "id": "264b5b33-944c-4994-9607-efc87c3eac24",
      "type": "RequiredPredecessor"
    },
    {
      "id": "fd4045cf-7260-4d7c-8b1f-9094b7e9664d",
      "type": "MultiplePredecessor"
    },
    {
      "multiplePredecessor": [
        {
          "ref": "qbqxvUsFihJawa4LJhRGVgCc0m5azQUwazYBa2R8/XDX7AQoFd5D9T3p0id73VHEG976TKYF9nZ0O21kFWrvDA=="
        }
      ],
      "optionalPredecessor": {
        "ref": "r3CkTFMiA36c6ryVsPPmlXz7ShisrfDBjInDKig8VP+OycVx1FRu4JqLTV3Xzys2ztHBkrpwOKPfhIaCl740aA=="
      },
      "requiredPredecessor": {
        "ref": "folx8LFZ9OYJvh4c6+Ivb/MRcbfqUjnNfnkOmuJSpX4qPlNrojqTL7qbdABa/PmAgWp4778CSz3Q9MowCqErgw=="
      },
      "type": "FactType"
    },
    {
      "factType": {
        "ref": "uySz8eyuD5QpLhNfFqFuzKQItT7vHoZvMTraHWS7uj5+mtwySFTStsdgfE4oNeXxR2n+J071RTIxj2hE2mjaGg=="
      },
      "type": "MultipleSuccessor",
      "value": "ae6359e4-cfc0-4609-b04a-7b4c685cc21d"
    },
    {
      "type": "OptionalPredecessor"
    },
    {
      "id": "449ed864-c4de-4812-8a0d-4cc88698aaf3",
      "type": "RequiredPredecessor"
    },
    {
      "id": "1fcc37c2-2cad-4ece-9016-64515105e03a",
      "type": "MultiplePredecessor"
    },
    {
      "multiplePredecessor": [
        {
          "ref": "9F5H43KBmUK5yI2awNquMl23O4uGzOEYYa0XJUzQKMNT9bEfchWdHtNIjYVwgW8fJ8jgYmt0RpT21jzs3vAZ3w=="
        },
        {
          "ref": "qbqxvUsFihJawa4LJhRGVgCc0m5azQUwazYBa2R8/XDX7AQoFd5D9T3p0id73VHEG976TKYF9nZ0O21kFWrvDA=="
        }
      ],
      "optionalPredecessor": {
        "ref": "OptionalPredecessor=null"
      },
      "requiredPredecessor": {
        "ref": "F5UNzt5chWLyGwtRO9WYW1CPnOHnWf7skI8HRHZKm5iHDtwuLkf7XzJHdDovLG3UpNYr5yOctYAvFyxlQs0RlA=="
      },
      "type": "FactType"
    },
    {
      "factType": {
        "ref": "dvMEoaAN9R4jPoggSsgVSwAbxMRcLXYGEqJpRm+BoiYzGOo+3rMUE6eIGMvTvjgJ2Puu5uSgNmGXqW60TIdP9A=="
      },
      "type": "MutableSuccessor",
      "value": "58ee09f3-7730-4818-85f3-3e0367689022"
    },
    {
      "factType": {
        "ref": "uySz8eyuD5QpLhNfFqFuzKQItT7vHoZvMTraHWS7uj5+mtwySFTStsdgfE4oNeXxR2n+J071RTIxj2hE2mjaGg=="
      },
      "type": "MutableSuccessor",
      "value": "0b0ac0b6-5351-4b8b-8b39-15226bab422d"
    },
    {
      "factType": {
        "ref": "dvMEoaAN9R4jPoggSsgVSwAbxMRcLXYGEqJpRm+BoiYzGOo+3rMUE6eIGMvTvjgJ2Puu5uSgNmGXqW60TIdP9A=="
      },
      "type": "MultipleSuccessor",
      "value": "6d38408a-ea9a-456c-8578-8d2fea064d90"
    },
    {
      "factType": {
        "ref": "uySz8eyuD5QpLhNfFqFuzKQItT7vHoZvMTraHWS7uj5+mtwySFTStsdgfE4oNeXxR2n+J071RTIxj2hE2mjaGg=="
      },
      "type": "MultipleSuccessor",
      "value": "28d94a61-a207-4ce2-ac84-47649b97f6a6"
    },
    {
      "factType": {
        "ref": "dvMEoaAN9R4jPoggSsgVSwAbxMRcLXYGEqJpRm+BoiYzGOo+3rMUE6eIGMvTvjgJ2Puu5uSgNmGXqW60TIdP9A=="
      },
      "type": "MultipleSuccessor",
      "value": "3d8462c5-5a89-40b6-87e8-484c516cdd8e"
    }
  ],
  "factTypes": [
    "OptionalPredecessor{id:string}",
    "RequiredPredecessor{id:string}",
    "MultiplePredecessor{id:string}",
    "FactType{multiplePredecessors:MultiplePredecessor*;optionalPredecessor:OptionalPredecessor?;requiredPredecessor:RequiredPredecessor}",
    "MultipleSuccessor{factType:FactType;value:string}",
    "OptionalPredecessor{}",
    "MutableSuccessor{factType:FactType;prior:MutableSuccessor*;value:string}"
  ]
}

Type Definitions

Optional Predecessor

OptionalPredecessor{id:string}

Required Predecessor

RequiredPredecessor{id:string}

Multiple Predecessor

MultiplePredecessor{id:string}

Fact Type

FactType{multiplePredecessors:MultiplePredecessor*;optionalPredecessor:OptionalPredecessor?;requiredPredecessor:RequiredPredecessor}

Multiple Successor

MultipleSuccessor{factType:FactType;value:string}

Mutable Successor

MutableSuccessor{factType:FactType;prior:MutableSuccessor*;value:string}