WRIT Docs

#Glossary

A comprehensive reference of terms used throughout WRIT and kbpy.

#Core Domain Model

Term Definition
Entity Type The schema — defines what kind of thing exists and what attributes it has. Like a class definition.
Entity Set A collection of entity instances, loaded from attestation data. Like a table of rows.
Entity A single instance of an entity type within an entity set. Like a row.
Exhaustive set A complete collection — if an entity is not in it, it definitely does not exist. Missing lookups return Void.
Partial set An incomplete collection — missing entities might exist elsewhere. Missing lookups return Unknown.
Attribute A property of an entity type (e.g. salary, name). Defined in the DSL with type, source field, and sentinel values.
Relationship A link between entity types (e.g. Employee → Department). Traverses from one entity set to another via matching attributes.
Domain A complete knowledge base — entity types, expectations, and data sources for a particular area of concern.

#Expectations and Alignment

Term Definition
Expectation A declaration that certain partition branches should be empty. The core unit of alignment measurement.
Expector The stakeholder who holds the expectation — the person or team who wants something to be true.
Expectee The entity responsible for making the expectation true — who should act when there is misalignment.
Campaign An expectation with no step towards clause — the root of a scope tree. Scoping to a campaign brings all descendant expectations (via step towards) into scope. All evaluation is scoped to a campaign.
Action A step to bring reality in line with an expectation. Directed at the expectee when an expectation evaluates to false.
Question A request for missing data. Directed at the attestor when data is unknown.

#Data and Attestation

Term Definition
Attestation A piece of data with a timestamp — someone or something asserted this fact at this time.
Attestor The person or system that provided an attestation. When data is missing or stale, questions are directed to the attestor.
Attestation Source Where attestation data comes from — a CSV file, a Splunk query, a database. Each source has an attestor.
FluentFact A time-aware attribute descriptor. Produces 3vl values and tracks staleness. Named after the AI concept of a "fluent" — a fact that changes over time.
Steward A named relationship from an entity set to a responsible stakeholder entity. Used in expectee traversals.

#Three-Valued Logic

Term Definition
Three-valued logic (K3) Kleene's three-valued logic system. Values are true, false, or unknown. Used throughout WRIT for evaluation.
Unknown A 3vl state meaning "the value exists but we do not know it yet." Generates questions.
Void A 3vl state meaning "the value cannot exist — the precondition failed." Does not generate questions. Stronger than Unknown in logical operations.
Uncertain The UI display term for Unknown values. Users see "uncertain" rather than the technical "unknown."
Reason chain A tuple of strings tracking how a value was derived, providing full provenance for debugging.

#Evaluation

Term Definition
Partition A predicate that classifies entities into five branches: is_true, is_false, is_known, is_unknown, is_void.
Predicate A logical expression that evaluates an entity and returns a three-valued result. Used within partitions to classify entities.
Typed unknown A synthetic entity with all-Unknown attributes, added to partial sets to discover what attributes matter and who to ask about missing data.
Scoped registry A filtered copy of the domain registries containing only data relevant to a specific campaign.
Unknown Discovery Problem The fact that unknown counts can only be determined by evaluating every entity through every predicate — missing data alone is insufficient because Kleene logic can absorb unknowns into definite results.

#System Components

Term Definition
kbpy The knowledge base engine. Parses domain DSL, evaluates expectations, generates questions and actions.
writ-kb The Remix web application for visualising domain state, expectations, and evaluation results.
DSL Domain Specific Language. The .kb file format used to define domains in kbpy.
DatomStore SQLite-backed entity-attribute-value store used by kbpy for persistence.

#See Also