Artefact

Artefacts (note the Australian spelling) are made objects. In an Artefactory they represent a fragment of knowledge — typically abstract, insightful, contextual.

An %Artefact{} is a small, self-contained property graph: nodes with labels and properties, connected by typed directed relationships. The canonical form is the Elixir struct. Arrows JSON and Cypher are derived representations — JSON for interchange and visual editing with Arrows.app, Cypher for persistence in Neo4j.

As we yarn we naturally exchange and create Artefacts.

Installation

def deps do
  [
    {:artefact, "~> 0.1"}
  ]
end

Building an Artefact

require Artefact

matt  = %Artefact.Node{
  id: "n0", uuid: "019da897-f2de-77ca-b5a4-40f0c3730943",
  labels: ["Agent", "Me"],
  properties: %{"name" => "Matt"}
}

claude = %Artefact.Node{
  id: "n1", uuid: "019da897-f2de-768c-94e2-3005f2431f37",
  labels: ["Agent", "You"],
  properties: %{"name" => "Claude"}
}

us_two = Artefact.new(
  title: "UsTwo",
  base_label: "UsTwo",
  graph: %Artefact.Graph{
    nodes: [matt, claude],
    relationships: [
      %Artefact.Relationship{
        id: "r0", from_id: "n0", to_id: "n1",
        type: "US_TWO", properties: %{}
      }
    ]
  }
)

The base_label is a watermark applied to every node at output time — it identifies which artefact a node belongs to without polluting the struct itself.

Exporting

# Cypher — MERGE upserts by uuid identity, CREATE always makes new nodes
Artefact.Cypher.merge(us_two)
Artefact.Cypher.create(us_two)

# Parameterised Cypher for driver use (e.g. Bolty)
{cypher, params} = Artefact.Cypher.merge_params(us_two)

# Arrows JSON — for round-trip with Arrows.app
Artefact.Arrows.to_json(us_two)

Combining and Extending Artefacts

# compose — disjoint union, nodes remain independent
combined = Artefact.compose(a1, a2)

# combine — pipeline-friendly union; bindings auto-found via shared uuid.
# Delegates to harmonise. Raises MatchError if no shared nodes.
my_knowing
|> Artefact.combine(my_valuing)
|> Artefact.combine(my_being)
|> Artefact.combine(my_doing, title: "MeMind", description: "Mind of Me")

# harmonise — union via declared bindings.
# Lower uuid wins identity, labels are unioned, left wins on property conflict.
{:ok, bindings} = Artefact.Binding.find(a1, a2)
harmonised = Artefact.harmonise(a1, a2, bindings)

# graft — extend an existing artefact inline with new nodes and
# relationships. args matches Artefact.new's inline shape, but every
# node MUST carry :uuid (no auto-find — uuid is the binding).
# Nodes whose uuid lives in left bind to it (labels unioned, properties
# merged left-wins). Nodes with new uuids are added.
me_mind
|> Artefact.graft(
     [
       nodes: [
         {:me,          [uuid: "019ddb71-c70b-7b3e-83b1-58f4d0be2852"]},   # bind-only
         {:stewardship, [labels: ["Knowing"], uuid: "019df318-698c-77d6-bc7b-ea041a019a7f"]}
       ],
       relationships: [[from: :me, type: "KNOWING", to: :stewardship]]
     ],
     title: "MeMind + Stewardship",
     description: "Stewardship grafted onto MeMind."
   )

Provenance is recorded automatically — every artefact carries metadata describing how it was created, including the calling module and, for derived artefacts, a summary of each source.

Importing from Arrows JSON

artefact = Artefact.Arrows.from_json!(json, diagram: "path/to/source.json")

Acknowledgements

Artefactory is inspired by Indigenous Systems Thinking and the profound wisdom presented by Tyson Yunkaporta in Sand Talk, grounded in countless years of sustainable, harmonious living.

License

MIT — see LICENSES/MIT.txt.