> ## Documentation Index > Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Domain Model > Record families, shared fields, and the Rust types behind Meerkat Recall's evidence and knowledge graph Use this page to locate a record and understand its relationships to other records. Start with the [knowledge model](/recall/concepts/overview) for the conceptual explanation, or the [HTTP reference](/recall/api/overview) for request bodies and response envelopes. | Reader question | Record family | | - | - | | Where did this information come from? | `Source`, `Doc`, `DocRevision`, `DocNode`, `Assertion` | | Which thing and which claim does it describe? | `Entity`, `Rel`, `Attribute`, `Event` | | How were competing claims reconciled? | `ConflictGroup`, `TruthSlot`, `PredicateRegistry` | | Why did processing stop or retry? | `WorkItem`, `WorkRun`, `WorkArtifact` | | Which compiled view is the reader seeing? | `KnowledgeView`, `KnowledgeViewRevision`, `KnowledgeViewDefinition` | | What access and provenance apply? | `BaseFields`, `Security`, `Provenance` | The Rust excerpts below omit serialization annotations and selected supporting fields. They are not request templates: API JSON generally flattens `BaseFields` into the record, serializes links as record ID strings, and uses snake-case enum values. Use the corresponding endpoint schema when constructing a request. ## RecordId System Every record in Meerkat Recall is identified by a `RecordId` -- a typed Meerkat Recall record identifier with the format `table:uuid` (for example, `entity:550e8400-e29b-41d4-a716-446655440000`). ```rust theme={null} pub struct RecordId { pub table: TableName, pub id: Uuid, } ``` New IDs are created with `RecordId::new_v4(table)` (random) or `RecordId::new_v7(table)` (time-ordered). The `table` component is drawn from the `TableName` enum, which lists every core table in the system. ### TableName Enum | Table Name | Variant | Description | | - | - | - | | `entity` | `Entity` | People, orgs, apps, topics -- the graph nodes | | `rel` | `Rel` | Entity-to-entity relationships | | `attribute` | `Attribute` | Entity-to-literal claims | | `doc` | `Doc` | Ingested documents | | `media_asset` | `MediaAsset` | Managed media bytes and metadata | | `doc_revision` | `DocRevision` | Immutable rendered text snapshots | | `doc_node` | `DocNode` | Structural chunks within a revision | | `doc_chunk` | `DocChunk` | Legacy document chunks; active code uses `doc_node` | | `chunk_embedding` | `ChunkEmbedding` | Vector embeddings for document nodes | | `assertion` | `Assertion` | Evidence-bearing claims with resolution state and preserved mention strings | | `truth_slot` | `TruthSlot` | Derived current claim selection for a slot | | `conflict_group` | `ConflictGroup` | Competing claims grouped for resolution | | `source` | `Source` | Provenance records (email, web, file, etc.) | | `work_item` | `WorkItem` | Durable work queue items | | `work_item_archive` | `WorkItemArchive` | Cold terminal work history | | `work_edge` | `WorkEdge` | DAG dependencies between work items | | `work_run` | `WorkRun` | Individual execution attempts | | `work_run_archive` | `WorkRunArchive` | Cold completed execution history | | `work_artifact` | `WorkArtifact` | Staged outputs from work runs | | `work_deadletter` | `WorkDeadletter` | Failed items for operator review | | `predicate_registry` | `PredicateRegistry` | Canonical predicate vocabulary | | `predicate_alias` | `PredicateAlias` | Alias mappings for predicates | | `space_config` | `SpaceConfig` | Per-space embedding and extraction config | | `system_event` | `SystemEvent` | Outbox events with monotonic sequence | | `event` | `Event` | Domain timeline events | | `audit_log` | `AuditLog` | Immutable audit trail | | `entity_identity_key` | `EntityIdentityKey` | Stable identity keys for entities | | `identity_candidate` | `IdentityCandidate` | Proposed entity merge candidates | | `entity_merge` | `EntityMerge` | Entity merge lineage | | `rel_evidence` | `RelEvidence` | Evidence linking rels to sources | | `id_map` | `IdMap` | Legacy ID mappings | | `ingest_decision` | `IngestDecision` | Deduplication decisions during ingest | | `cost_ledger_daily` | `CostLedgerDaily` | Daily cost tracking | | `freshness` | `Freshness` | Freshness scores for staleness detection | | `reprocess_job` | `ReprocessJob` | Backfill and re-extraction jobs | | `knowledge_view` | `KnowledgeView` | Stable identity and lifecycle for a derived view | | `knowledge_view_revision` | `KnowledgeViewRevision` | Immutable compiled view revision | | `knowledge_view_definition` | `KnowledgeViewDefinition` | Governed typed definition of a graph-derived view | | `knowledge_view_dependency` | `KnowledgeViewDependency` | Reverse dependency used for view invalidation | | `source_watch` | `SourceWatch` | Durable refresh policy for a remote source | | `source_watch_check` | `SourceWatchCheck` | Receipt for one remote source observation | The derived view and watch records are described in [Living Wiki architecture](/recall/architecture/living-wiki). Cold work history keeps the original public IDs; see [work queue history](/recall/pipeline/work-queue#indexed-queue-and-historical-work). ### Link\ `Link` is a typed foreign-key reference to another record. The generic parameter `T` indicates the expected target type for compile-time safety, while the underlying storage is a `RecordId`. ```rust theme={null} pub struct Link { pub id: RecordId, // PhantomData for type safety } ``` Use `link.id()` to read the underlying `RecordId`, or `link.into_id()` to consume it. *** ## BaseFields Every core record embeds `BaseFields`, which carries identity, multi-tenancy, timestamps, provenance, security, and subject scoping. ```rust theme={null} pub struct BaseFields { pub id: RecordId, pub space_id: String, pub created_at: DateTime, pub updated_at: DateTime, pub created_by: String, pub deleted_at: Option>, pub provenance: Provenance, pub security: Security, pub subjects: Vec>, pub subjects_state: SubjectsState, } ``` | Field | Purpose | | - | - | | `id` | Unique `RecordId` for this record. | | `space_id` | Multi-tenant scope, such as a workspace, project, or organization. | | `created_at` / `updated_at` | Lifecycle timestamps. | | `created_by` | Agent or service that created the record. | | `deleted_at` | Soft-delete marker. `None` when active. | | `provenance` | Source chain, extractor metadata, and work run linkage. | | `security` | ABAC labels: `policy_id`, `level`, `labels`, `handling`. | | `subjects` | Entity links for subject-scoped access control. | | `subjects_state` | Whether subjects are `complete`, `partial`, or `unknown`. | Soft-delete marks a record without removing its stored representation. Ordinary reads filter deleted records; explicit history, recovery, or `include_deleted` reads may expose them when authorized. Retention and purge are separate operations. Do not use a soft-delete marker as a data-erasure guarantee. ### Provenance ```rust theme={null} pub struct Provenance { pub sources: Vec, pub extractor: Option, pub work_run_id: Option, pub run_id: Option, pub prompt_id: Option, pub config_id: Option, pub chain: Vec, } ``` ### Security (ABAC Envelope) ```rust theme={null} pub struct Security { pub policy_id: String, pub level: i32, pub labels: Vec, pub handling: Vec, } ``` *** ## Knowledge Graph Records ### Entity Core nodes in the knowledge graph. Entity types are freeform lowercase strings (e.g., `person`, `org`, `topic`, `app`). ```rust theme={null} pub struct Entity { pub base: BaseFields, pub entity_type: EntityType, // freeform string, e.g. "person" pub display_name: String, pub aliases: Vec, pub summary: Option, pub handles: Vec, pub identity_keys: Vec, pub risk_level: Option, pub trust_level: Option, pub known_safe: bool, pub first_seen: Option>, pub last_seen: Option>, pub status: EntityStatus, // Active | Merged pub redirect_to: Option>, pub metadata: Value, } ``` When an entity is merged, `status` becomes `Merged` and `redirect_to` points to the surviving entity. ### Rel Entity-to-entity relationships. The `subject` ("from") and `object` ("to") are both entity links. ```rust theme={null} pub struct Rel { pub base: BaseFields, pub subject: Link, // "in" side pub object: Link, // "out" side pub rel_type: String, // canonical predicate pub status: ClaimStatus, // Candidate | Approved | Superseded | Disputed pub confidence: f32, pub validity_window: Option, pub evidence: Vec, pub temporal_audit: Option, } ``` `ClaimStatus` tracks the lifecycle from initial candidate through promotion to approved status. `ValidityWindow` models temporal claims with optional start/end bounds. ### Attribute Entity-to-literal claims. Like `Rel`, but the object is a typed `Literal` value rather than an entity. ```rust theme={null} pub struct Attribute { pub base: BaseFields, pub subject: Link, pub attr_type: String, // canonical predicate pub value: Literal, // String | Integer | Float | Boolean | Date | DateTime | Duration | Json pub status: ClaimStatus, pub confidence: f32, pub validity_window: Option, pub evidence: Vec, pub temporal_audit: Option, } ``` *** ## Document Pipeline Records ### Doc Top-level source-backed document record ingested into Meerkat Recall. For media-backed ingest, `text` is the renderer-owned canonical searchable projection rather than the raw caller payload. ```rust theme={null} pub struct Doc { pub base: BaseFields, pub title: String, pub text: String, pub sidecar_text: Option, pub source: Option>, pub media_attachments: Vec, pub rendition_key: String, pub metadata: Value, } ``` ### DocRevision Immutable normalized text snapshot produced by a renderer plugin. For multimodal docs, the revision also carries the authoritative render manifest that maps spans back to attachments and time ranges. If rendering improves, a new revision is created and the old one is superseded. ```rust theme={null} pub struct DocRevision { pub base: BaseFields, pub doc: Link, pub text: String, pub text_hash: String, pub manifest: Option, pub renderer: RendererMetadata, pub supersedes: Option>, pub status: RevisionStatus, // Active | Superseded | Failed pub rendered_at: DateTime, } ``` ### DocNode Structural nodes over a revision -- paragraphs, sections, chunks, summaries, etc. ```rust theme={null} pub struct DocNode { pub base: BaseFields, pub revision: Link, pub role: NodeRole, // Document | Section | Paragraph | Chunk | Summary | ... pub span: TextSpan, // { start: u32, end: u32 } pub node_key: String, pub text: Option, pub parent: Option>, pub position: i32, pub depth: i32, pub embedding_model: Option, pub collection: Option, } ``` *** ## Extraction and Truth Maintenance ### Assertion Evidence-bearing claims extracted from documents by the LLM extraction pipeline. Assertions preserve the original mention strings alongside their resolution status and optional resolved entity links. Staged artifact validation/commit resolves or creates graph records; later truth maintenance reconciles competing graph claims. A `resolved` assertion is not a guarantee that its claim is true. ```rust theme={null} pub struct Assertion { pub base: BaseFields, pub subject_text: String, pub predicate_raw: String, pub predicate_id: Option, pub object_text: Option, pub object_literal: Option, pub evidence: EvidenceSpan, pub source_event_time: Option>, pub observed_at: DateTime, pub asserted_at: DateTime, pub assertion_key: String, pub resolution_status: ResolutionStatus, // Pending | Resolved | Partial | Abstained | Failed | Superseded pub resolution_method: Option, pub resolution_confidence: Option, pub retry_state: AssertionRetryState, pub subject_entity: Option>, pub object_entity: Option>, pub confidence: f32, pub subject_entity_type: Option, pub object_entity_type: Option, pub significance: Option, pub lifecycle_tier: String, // "active" | "archived" } ``` ### TruthSlot The derived current selection for a claim slot. Each `current_values` entry references a graph claim by `claim_id`, with its confidence, status, and evidence. It does not contain the literal value itself. Read that claim to obtain its value. A slot can have several accepted values, be stale, or require more evidence; it is not an independent source of evidence. ```rust theme={null} pub struct TruthSlot { pub base: BaseFields, pub slot_key: String, pub slot_type: String, // "rel" | "attribute" | "event" | "rel_set" pub subject_entity: String, pub predicate_id: String, pub current_values: Vec, pub conflict_group: Option>, pub confidence: f32, pub rationale: Option, pub semantics_version: u32, pub alias_version: u32, pub stale: bool, pub stale_reason: Option, pub computed_at: DateTime, pub security_hash: String, } ``` *** ## Source Provenance ### Source Tracks where data came from -- emails, web pages, chat messages, device captures, manual entries, etc. ```rust theme={null} pub struct Source { pub base: BaseFields, pub type_: SourceType, // Email | Calendar | Web | Drive | Chat | DeviceFrame | DeviceVideo | Transcript | Manual pub external_id: Option, pub uri: Option, pub path: Option, pub parent: Option>, pub range: Option, pub timestamp: Option>, pub author: Option, pub channel: Option, pub hash: String, pub metadata: Value, } ``` *** ## Work Scheduler Records The durable work scheduler uses a DAG-based queue with lease-based execution. Each pipeline stage produces `WorkItem` records that are claimed, executed, and produce artifacts. ### WorkItem ```rust theme={null} pub struct WorkItem { pub base: BaseFields, pub kind: String, // e.g. "render_doc", "plan_extraction", "extract_assertions", "validate_artifacts", "commit_artifacts" pub payload: Value, pub status: WorkItemStatus, // Pending | Runnable | Running | Done | Failed | Cancelled pub priority: i32, pub idempotency_key: String, pub attempts: u32, pub lease_expires_at: Option>, pub leased_by: Option, pub run_after: Option>, pub last_error: Option, } ``` ### WorkRun A single execution attempt of a work item. ```rust theme={null} pub struct WorkRun { pub base: BaseFields, pub work_item: Link, pub attempt: u32, pub started_at: DateTime, pub completed_at: Option>, pub success: bool, pub error: Option, pub metrics: WorkRunMetrics, pub worker_id: String, pub worker_version: String, pub model_version: Option, pub prompt_id: Option, pub config_hash: Option, } ``` ### WorkArtifact Staged output produced by a work run. Goes through validation before being committed to canonical tables. ```rust theme={null} pub struct WorkArtifact { pub base: BaseFields, pub work_run: Link, pub artifact_type: String, // e.g. "knowledge_candidates", "commit_bundle" pub data: Value, pub status: ArtifactStatus, // Draft | Validated | Committing | Committed | Rejected pub validation_errors: Option>, pub validated_at: Option>, pub committed_at: Option>, } ``` *** ## Configuration and Governance ### SpaceConfig Per-space configuration controlling embedding provider selection and extraction behavior. ```rust theme={null} pub struct SpaceConfig { pub base: BaseFields, pub embedding_provider: String, // "fastembed" | "openai" | "fake" pub embedding_model: String, pub embedding_dims: i32, pub purpose: Option, // injected into extraction prompts pub skill: Option, // extraction skill ID } ``` ### PredicateRegistry Canonical predicate definitions with semantic configuration that drives truth maintenance behavior. ```rust theme={null} pub struct PredicateRegistry { pub base: BaseFields, pub predicate_id: String, pub description: Option, pub status: String, // "active" | "deprecated" pub semantics: Option, pub semantics_status: SemanticsStatus, pub first_seen_at: Option>, pub usage_count: u64, pub last_used_at: Option>, } ``` `PredicateSemantics` controls temporal model, cardinality, conflict policy, recency basis, promotion thresholds, and alias confidence thresholds. ### PredicateAlias Maps raw extraction strings to canonical predicates with confidence-scored aliases. ```rust theme={null} pub struct PredicateAlias { pub base: BaseFields, pub alias: String, pub alias_type: AliasType, // RawString | PluginCode | SchemaField pub source_plugin: Option, pub confidence: f32, pub status: AliasStatus, // Proposed | Active | Deprecated pub scope: AliasScope, // Global | PluginOnly | SourceType pub predicate_id: String, pub confidence_version: u32, pub usage_count: u64, } ``` *** ## System Records ### Event First-class domain timeline events with temporal precision and evidence links. ```rust theme={null} pub struct Event { pub base: BaseFields, pub title: String, pub summary: Option, pub status: EventStatus, // Candidate | Approved | Superseded | Rejected pub time_start: Option>, pub time_end: Option>, pub time_precision: TimePrecision, // Exact | Minute | Hour | Day | Month | Year | Unknown pub confidence: f32, pub time_confidence: f32, pub assertion_refs: Vec>, pub source_refs: Vec>, pub metadata: Value, } ``` ### SystemEvent Outbox events for reliable change-data streaming. Each carries a monotonic sequence number. ```rust theme={null} pub struct SystemEvent { pub base: BaseFields, pub seq: i64, pub event_type: String, pub payload: Value, } ``` ### AuditLog Audit entries record supported mutations with optional before/after snapshots. The record type alone does not guarantee that every internal mutation emits an entry. Consult the mutation handler and [audit revert contract](/recall/api/system#audit-revert) when building an administrative recovery workflow. ```rust theme={null} pub struct AuditLog { pub base: BaseFields, pub action: AuditAction, // Create | Update | Delete | Restore | Purge | Promote | Merge pub actor: String, pub record: RecordId, pub before: Option, pub after: Option, pub timestamp: DateTime, pub reason: Option, } ``` All struct definitions above are simplified for documentation purposes. Derive macros, `impl` blocks, and serde attributes are omitted. See the actual source in `crates/types/src/records/` for the full definitions. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.