Archipelago
GitHub

Documentation · design

The provenance model

Design document. Describes the first platform release, which is not yet built.

Provenance: every fact in the model is observed from a live device, imported from an engineering file, inferred by a rule with a confidence, or confirmed by a person. Nothing is overwritten; confirmations supersede.OBSERVEDIMPORTEDINFERREDCONFIRMEDread from a live devicefound in an engineering fileby a rule · confidence 0.00–1.00by a named person, datedsource: connector id,device, object, timesource: file hash,locator inside the filesource: rule id, the factsit used, the scoresupersedes an earlier fact;nothing is overwrittenbelow threshold → a question for a technician
Fig. Provenance. Four labels, carried by every fact, shown on every screen, returned by every API call.

Assertions

The unit of knowledge is an assertion: a subject, a statement, and a provenance. "VAV-214 has point ZN_T" is an assertion. "VAV-214 is served by AHU-3" is an assertion. Each carries exactly one of four provenance kinds.

observed   { source: connector id, native ref, time }
imported   { artifact: sha256, locator inside the file }
inferred   { rule id, the assertions it used, confidence 0–1 }
confirmed  { person, time, the assertion it supersedes }
rejected   { person, time, the assertion it supersedes }

Nothing is overwritten

A confirmation or a rejection is a new assertion that supersedes an older one. The interface shows the current view; the API can return the chain. A re-import produces a new snapshot; confirmed facts are never replaced by imported ones, and the diff of what an import would change is shown before it is accepted.

Questions

An inferred assertion below the confidence threshold, or a conflict between two sources, becomes a question with the evidence attached, queued for a technician. Answering writes a confirmed or rejected assertion. The count of open questions is a headline number on every site.

Artifacts and redaction

An artifact (a backup, a controller file, a schedule) is stored content-addressed and encrypted at rest. The model refers to it by hash and locator. No endpoint serves its bytes. Passwords, tokens and certificates found inside it are replaced at import with a typed placeholder that records the locator and the kind, never the value. There is no code path that stores the bytes.

Snapshots and diff

A snapshot is an immutable, hashed set of assertions plus the hashes of the artifacts it came from. Diffing two snapshots matches on persisted identity first: the same handle and type is the same component even if renamed or moved; only unmatched components fall back to the same name under an already-matched parent. Links compare by meaning, not by handle string.

What the model refuses to say

Anything the source does not contain. A wiresheet is a graph of blocks; the model records what is linked to what, not what the sequence means. A controller file lists exposed objects; the model records the objects, not the logic. Unknown vendor types are decoded generically and reported as unknown, not guessed.