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

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

The permitted values are enumerated in the constant SOURCE_STATUSES defined in 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.

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

{"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.

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 defines the schema and validation logic, the 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}