# Review Statuses for Sources in the Claude-Obsidian Ledger: The Complete Guide

> Master Claude-Obsidian review statuses: unreviewed, active, superseded, and rejected. Understand source reliability and workflow in this complete guide.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Claude-Obsidian defines four distinct review statuses—`unreviewed`, `active`, `superseded`, and `rejected`—to track source reliability and workflow state within its provenance ledger system.**

The claude-obsidian project implements a rigorous provenance tracking system for knowledge vaults, where every source entry includes a **`review_status`** field to indicate its position in the validation workflow. Understanding these **review statuses for sources in the claude-obsidian ledger** is essential for maintaining data integrity and ensuring that downstream claim validation operates on trusted, correctly categorized information.

## The Four Source Review Statuses Defined

The `review_status` field accepts exactly four string values, each representing a specific state in the source lifecycle. These values govern whether a source may be referenced to support claims or should be excluded from active use.

### `unreviewed`

The **`unreviewed`** status indicates that a source has been added to the vault but has not yet undergone formal examination or approval. Sources in this state exist in the ledger for tracking purposes but are not considered reliable enough to support active claims.

### `active`

The **`active`** status signals that a source has completed review and is considered reliable. Only sources marked as `active` should be used to substantiate claims or assertions within the knowledge base. This status represents the production-ready state for provenance-backed content.

### `superseded`

The **`superseded`** status marks sources that have been replaced by newer versions or updated editions. When a source is superseded, it should no longer be referenced for new claims, though it remains in the ledger for historical audit purposes. The `supersedes` field in a source record typically links to the replacement entry.

### `rejected`

The **`rejected`** status identifies sources that failed review due to quality issues, credibility concerns, or other disqualifying factors. Rejected sources must not be used to support any claims and serve as a blacklist to prevent contaminated information from entering the knowledge graph.

## Source Code Implementation in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py)

The permitted values are enumerated in the constant **`SOURCE_STATUSES`** defined in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) at line 39. This constant provides the authoritative set of allowed strings for the `review_status` field across the entire codebase.

```python

# From claude_obsidian/ledgers.py

SOURCE_STATUSES = {'unreviewed', 'active', 'superseded', 'rejected'}

```

Any operation that modifies source metadata must respect this constraint set. The ledger system references this constant during validation to ensure schema compliance.

## Validating Review Statuses with `validate_source_ledger`

The **`validate_source_ledger`** function enforces that every source record’s `review_status` field contains one of the four permitted values defined in `SOURCE_STATUSES`. When processing a ledger, the validator inspects each entry and returns structured error objects for any violations.

If an invalid status is detected, the validator produces an error with the following structure:

```python
{"path": "sources.<id>.review_status", "message": "unsupported review status"}

```

This strict validation guarantees consistency across the vault and enables downstream tools—such as freshness checkers and claim validators—to rely on the status field without defensive coding.

## Practical Python Examples for Managing Source Statuses

The following examples demonstrate how to create valid source entries, run validation, handle errors, and enumerate allowed statuses using the claude-obsidian API.

```python
from pathlib import Path
from claude_obsidian.ledgers import (
    validate_source_ledger,
    empty_source_ledger,
    stable_source_id,
    SOURCE_STATUSES,
)

# 1️⃣ Create a minimal source ledger with a single active source

vault_root = Path("/path/to/vault")
source_id = stable_source_id("file", "docs/example.md", None)
source_ledger = empty_source_ledger()
source_ledger["sources"][source_id] = {
    "origin": {"kind": "file", "locator": "docs/example.md"},
    "content_kind": "document",
    "title": "Example Document",
    "authority": "official",
    "content_sha256": None,
    "ingested_at": "2024-01-01",
    "retrieved_at": None,
    "refresh_due": "2024-06-01",
    "review_status": "active",          # ← valid status

    "independence_key": None,
    "pages": ["wiki/example.md"],
    "supersedes": None,
}

# 2️⃣ Run the ledger validator – it will accept the `active` status

errors = validate_source_ledger(source_ledger, vault_root=vault_root)
assert not errors, f"Validation failed: {errors}"

# 3️⃣ Attempt to set an invalid status – validator will report an error

source_ledger["sources"][source_id]["review_status"] = "pending"
errors = validate_source_ledger(source_ledger, vault_root=vault_root)
print(errors)   # → [{'path': 'sources.src‑… .review_status', 'message': 'unsupported review status'}]

# 4️⃣ Enumerate all allowed statuses (useful for UI dropdowns)

print(SOURCE_STATUSES)   # → {'unreviewed', 'active', 'superseded', 'rejected'}

```

## Integration with Transaction Processing

While [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) defines the schema and validation logic, the **[`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py)** module handles bundle reading and writing operations. This module indirectly invokes `validate_source_ledger` when applying transactions to ensure that all incoming source metadata conforms to the review status constraints before persistence.

## Summary

- Claude-Obsidian tracks four specific **review statuses** (`unreviewed`, `active`, `superseded`, `rejected`) to manage source lifecycle states.
- The **`SOURCE_STATUSES`** constant in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) defines the complete set of permitted values.
- The **`validate_source_ledger`** function enforces these constraints and returns structured errors for invalid statuses.
- Only sources marked as **`active`** should be used to support claims within the vault.
- Invalid statuses trigger validation errors with the message `"unsupported review status"` at the path `sources.<id>.review_status`.

## Frequently Asked Questions

### What are the four possible review statuses for sources in the claude-obsidian ledger?

The four permitted values are `unreviewed`, `active`, `superseded`, and `rejected`. These are defined in the `SOURCE_STATUSES` constant in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) and represent the complete set of states a source can occupy within the provenance workflow.

### How does claude-obsidian validate that a source has a legitimate review status?

The `validate_source_ledger` function checks every source entry against the `SOURCE_STATUSES` set. If a `review_status` field contains any value outside this set, the validator records an error with the path `sources.<id>.review_status` and the message `"unsupported review status"`.

### What happens if I accidentally set an invalid review status like "pending"?

The ledger validator will reject the entry and return an error list containing a dictionary specifying the invalid path and message. The transaction will not be applied until the status is corrected to one of the four allowed values.

### Where can I find the constant that defines the allowed review statuses?

The **`SOURCE_STATUSES`** constant is located in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) at line 39. This constant contains the Python set `{'unreviewed', 'active', 'superseded', 'rejected'}` and serves as the single source of truth for valid review status values across the codebase.