# Rules for working with Artefact ## Installation The preferred way to add Artefact to a project is via Igniter: ```bash mix igniter.install artefact ``` This wires up the formatter automatically. If your project does not use Igniter, add the dep manually and run `mix deps.get`. ## What Artefact is Artefact is an Elixir library for building, combining, and persisting knowledge graph fragments. An `%Artefact{}` is a named, typed property graph — a small, self-contained piece of knowledge. It is not an application data model, a database schema, or a general-purpose graph library. The intended use is knowledge memorialisation: capturing shared understanding between people, agents, or systems in a form that can be combined, versioned, and persisted. ## require Artefact `Artefact.new/1`, `Artefact.new!/1`, `Artefact.combine!/2`, and all other operations are **macros**. Always `require Artefact` before calling them: ```elixir require Artefact artefact = Artefact.new!( title: "Us Two", nodes: [ matt: [labels: ["Agent"], properties: %{"name" => "Matt"}], claude: [labels: ["Agent"], properties: %{"name" => "Claude"}] ], relationships: [ [from: :matt, type: "US_TWO", to: :claude] ] ) ``` Without `require`, you will get a compile-time error about undefined functions. This is the most common source of confusion when first using Artefact. ## UUID is identity Every node carries a UUIDv7 `uuid`. This is its identity — the same UUID in two artefacts means the same node. `combine!/2` uses UUID equality to find shared nodes and merge them. **Never change a UUID once it has been used in a persisted or shared artefact.** If you assign a UUID explicitly at construction time, keep it. If you do not assign one, Artefact generates a time-ordered UUIDv7 automatically. For importing from external sources — Mermaid diagrams, Cypher files, JSON — derive UUIDs deterministically from a stable identifier using `Artefact.UUID.from_name/1`: ```elixir uuid = Artefact.UUID.from_name("std_ulogic") # same name always → same UUID, valid UUIDv7 ``` This means the same external id imported twice always produces the same node, and `combine!/2` will bind correctly across imports. ## Operations at a glance | Operation | What it does | Key constraint | |---|---|---| | `new!/1` | Build a fresh artefact | Macro — `require Artefact` | | `combine!/2` | Union two artefacts via shared UUIDs | Different `base_label` required | | `harmonise!/3` | Union via explicit bindings | Different `base_label` required | | `compose!/2` | Concatenate — nodes stay disjoint | No shared UUIDs expected | | `graft!/2` | Extend an existing artefact inline | Every new node must carry `:uuid` | Each operation has a `!/n` (raises) and `/n` (returns `{:ok, _} | {:error, _}`) variant. ## combine!/2 requires different base_label values `combine!/2` finds shared nodes automatically by UUID. It requires the two artefacts to have **different** `base_label` values — this distinguishes "what I know" from "what I am adding": ```elixir # Raises Artefact.Error.Operation with same_base_label Artefact.combine!(a, b) # both default base_label to calling module name # Correct a = Artefact.new!(base_label: "Signals", ...) b = Artefact.new!(base_label: "Values", ...) combined = Artefact.combine!(a, b) ``` When no `base_label` is set explicitly, it defaults to the short name of the calling module — so two artefacts built in the same module will clash. ## Mermaid import and export `Artefact.Mermaid.export/2` converts an artefact to a Mermaid `graph` source string. `Artefact.Mermaid.from_mmd!/2` parses it back. The round-trip is lossless for: title, description, node names, labels, and relationship types. ### UUID identity anchors on the Mermaid node id When importing with `from_mmd!/2`, the UUID of each node is derived from its **Mermaid node id** — the `\w+` identifier (e.g. `val_0`, `std_ulogic`) — not the display label inside the shape. Keep node ids stable across diagram versions; changing an id changes the UUID and breaks bindings. ```mermaid graph LR std_ulogic(("std_ulogic
Signal")) ← id is std_ulogic, UUID derived from "std_ulogic" ``` ### Declare nodes separately from edges for label recovery When a node's shape is declared inline on an edge line, the label is not captured: ``` val_0["VALUE · 0"] -->|ENUMERATES| value ← label "VALUE" is lost ``` Use a separate declaration line: ``` graph LR val_0["VALUE · 0"] val_0 -->|ENUMERATES| value ``` The export format produced by `export/2` always uses separate lines, so this only applies to hand-authored Mermaid. ### Node label conventions in Mermaid Two formats are recognised inside node shapes: - `name
Label1 Label2` — our export format - `LABEL · name` — yarn convention (one label and name separated by ` · `) ### Node descriptions via click tooltips Node `description` properties are exported as `click id "text"` lines and recovered on import. They are visible as hover tooltips in Mermaid renderers. ## %Artefact{} struct shape ```elixir %Artefact{ uuid: "019e...", # UUIDv7 — the artefact's own identity title: "My Artefact", # optional description: "...", # optional base_label: "Concept", # optional — collapsed into per-node labels at export graph: %Artefact.Graph{ nodes: [ %Artefact.Node{ id: "n0", # internal sequential id — do not rely on this across artefacts uuid: "019e...", # UUIDv7 — stable identity labels: ["Concept", "Thing"], properties: %{"name" => "Alpha", "description" => "..."} } ], relationships: [ %Artefact.Relationship{ id: "r0", # internal sequential id type: "RELATES", # MACRO_CASE convention from_id: "n0", to_id: "n1", properties: %{} } ] } } ``` Node `id` values (`n0`, `r0`) are internal and sequential within one artefact. Use `uuid` for stable cross-artefact identity.