CLI Idempotency Analysis

Updated during documentation review: dossier create now exists in the CLI (see cli_dossier.py), and doc load was redesigned to always create a brand-new document with an auto-generated ID rather than updating an existing one. Sections below have been corrected to match current behavior.

Summary

The Thalabus CLI commands have varying levels of idempotency support:

✅ Fully Idempotent Commands (MERGE-based)

thalabus reasoning load <file> - Creates or updates ReasoningDocument (uses MERGE)
thalabus template load <file> - Creates or updates DocumentTemplate (uses MERGE)
thalabus dossier create <dossier_id> --name <name> - Creates dossier or reports "already exists" (idempotent check)

⚠️ Non-Idempotent by Design

thalabus doc load <file> - Always creates a new Document node with an auto-generated ID (docid-NNNN). It does not accept a document ID and cannot update an existing document. Running it twice on the same file creates two separate documents — this is intentional CLI behavior, not a partial/incomplete idempotency gap.

❌ Non-Idempotent Commands

Updating the text of an existing document via CLI - No CLI command currently exposes update_document()/similar for re-ingesting text into a pre-existing document node; doc load only creates new ones and doc save only exports (read-only) existing document text to a file.

Detailed Findings

1. Reasoning Document Loading (✅ IDEMPOTENT)

Command:

thalabus reasoning load <filename> [-i <document_id>]

Implementation: Uses MERGE on Neo4j level

MERGE (d:ReasoningDocument {id: $document_id})
SET d.enhanced_text = $document_content,
    d.text = $document_content,
    d.lastupdate_datetime = datetime()
RETURN d.id AS id, d.enhanced_text AS text

Idempotency: ✅ YES - Safe to run multiple times - First run: Creates new ReasoningDocument - Second run: Updates existing ReasoningDocument - No force flag needed - MERGE handles both cases

2. Template Loading (✅ IDEMPOTENT)

Command:

thalabus template load <filename> [-t <template_id>]

Implementation: Uses MERGE on Neo4j level

MERGE (t:DocumentTemplate {templateid: $template_id})
SET t.text = $template_content,
    t.lastupdate_datetime = datetime()
RETURN t.templateid AS templateid, t.text AS text

Idempotency: ✅ YES - Safe to run multiple times - First run: Creates new DocumentTemplate - Second run: Updates existing DocumentTemplate - No force flag needed - MERGE handles both cases

3. Document Text Loading (⚠️ ALWAYS CREATES — NOT UPDATE-CAPABLE)

Command:

thalabus doc load <filename>

Current Behavior (see _cmd_doc_load in cli_doc.py): 1. Only .txt files are accepted; any other extension is rejected. 2. A new document ID is always auto-generated via generate_new_document_id() — there is no document_id argument. 3. A new Document node is created with CREATE (not MERGE) — there is no code path that looks up or updates an existing document.

Idempotency Issue: - ❌ Running the same file twice creates two distinct documents with two different auto-generated IDs. - ❌ There is no way to target a specific existing document ID for re-ingestion via doc load. - ❌ No command currently exists to update the .text/.enhanced_text of an already-existing document from a file.

Recommendation: If update-in-place is needed, add a separate --id <DOCUMENT_ID> option (or a distinct doc update command) that uses MERGE/explicit SET against an existing node, rather than unconditional CREATE.

4. Dossier Creation (✅ AVAILABLE AND IDEMPOTENT)

Command:

thalabus dossier create <dossier_id> --name <name>

Implemented in cli_dossier.py. Confirmed available in the current CLI — the CLI reference (THALABUS_CLI.md) and the earlier draft of this document previously listed dossier creation as unavailable; that is no longer the case.

Current Idempotency Status Summary

✅ reasoning load    - Idempotent (MERGE-based)
✅ template load     - Idempotent (MERGE-based)
✅ dossier create    - Idempotent (checks existence, reports if found)
⚠️  doc load         - Always creates a new document with an auto-generated ID; cannot update existing documents
❌ doc update        - Not available in CLI (no way to re-ingest text into an existing document node)
✅ dossier ls        - Read-only, safe
✅ doc ls/show       - Read-only, safe
✅ category ls       - Read-only, safe
✅ ontology ls       - Read-only, safe

Overall Score: Reasoning/template loading and dossier creation are fully idempotent; document creation via doc load is intentionally non-idempotent (always creates new), and there is currently no CLI path to update an existing document's text.