Evidence and provenance

A house stores evidence, not verdicts. Three skills carry most of it; the examples below were run against a fresh house.

Notes: the reasoning beside the fact

add_note attaches an editorial note to any thing: who says it, when, in what words, and optionally which sources it leans on. It needs an author. For an agent, name_speaker creates one ("research-agent"); the same name finds it again. Notes hang on their thing as a chain, oldest first, and describe shows them. A note has no state and is never answered. Use it for "taken from the chronicle; the minutes have not been seen yet".

Conjectures: the recorded open question

raise_conjecture records that something might be so, without judging it. It points at its subject and starts as Open:

• list_conjectures is the worklist of open questions; overview counts them.
• resolve_conjecture with an answer closes one. Resolving means answering, never deleting; "does not apply" is an answer and stays.
• resolve_conjecture with needs_user_resolution set escalates one to the person who knows, instead of answering it.

A conjecture never creates the thing it suspects. Raising "this is probably the same person" merges nobody; the judgement is a separate act.

Reading how a thing stands

describe_evidence answers "how does the truth of this thing stand?" as a reading that is computed at every call, never as a stored stamp. The steps of its scale:

In the test, a claim with one open conjecture read Suspected, and after the conjecture was answered it read Dismissed. The answer lists the open items with their wording and their answers, so you see why.

What counts as a carrier is decided by the house, not by you. A carrier is something readable: a text, a paragraph of a document, or stored bytes, tied to the claim with assert_link(<claim>, <the readable thing>, 'Index'). A link form of your own ("Stated in", with a page) records where a statement stands, but it does not carry it: a claim linked only that way, or only to a record you defined, reads Unevidenced. Seen in two tests, the second with parish registers:

1. Keep the wording of the source as text: a document (create_document, import_document) or a Text property of your own record, such as Transcript.
2. Record where it stands with your own form, for example an entry with Register and Page.
3. Link the claim (a parenthood, a partnership, a fact) to the text with Index. describe_evidence on the claim then reads Evidenced.

A person is not evidenced by the entries that name them; the claims about the person are. Read the full description with read_skill before you build on the scale.

Who wrote what

Facts are retracted, not deleted, so a wrong statement stays readable as a retracted one; only erasing a whole thing on a person's order removes what belongs to it (your-data-stays-yours). Versioned slots keep every earlier wording (get_history). Documents keep every version. Two identities found to be one are joined with merge_into, which leaves a tombstone and can be undone with unmerge; two found to be different are recorded with assert_separate, so that no later pass merges them by mistake.

Go deeper

• Documents and versions: where the carrying texts live
• Finding things
• The building blocks