# 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:

| Reading | Meaning |
|---|---|
| Unevidenced | asserted, nothing carries it |
| Suspected | nothing carries it, and an unanswered open item points at it |
| Dismissed | nothing carries it, and the open items about it are answered |
| Evidenced | one carrier |
| MultiplyEvidenced | more than one carrier |
| EvidencedThroughout | a computed chain whose every link has a carrier |
| Disputed | an open contradiction |

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, never deleted, so a wrong statement stays readable as a retracted
one. 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](documents-and-versions.md): where the carrying texts live
- [finding-things](finding-things.md)
- [the-building-blocks](the-building-blocks.md)