Architecture & Foundation
Docs » Architecture & Foundation » Fail-Closed Error Propagation & Transaction Resilience
Raw .md

Fail-Closed Error Propagation & Transaction Resilience

Document ID: DOC-FAIL-CLOSED-ERROR-PROPAGATION-001
Status: Approved / Enforced
Technical Debt Reference: TDE-F-CQ-001

1. Overview

Silent error swallowing via blank identifiers (_ = err) and mechanical logging (logging.LogSwallowedError) compromises data consistency, masks concurrency deadlocks, and allows corrupted state mutations to proceed.

This standard establishes strict invariants for transaction commits, state transitions, and concurrency locks across the Knowledge Kernel and CLI surfaces.

2. Core Invariants & Rules

Rule 1: Fail-Closed Transaction Rollbacks

  • All database and storage transactions (sp.BeginTransaction(ctx)) must be guarded by explicit error handling.
  • If creating idempotency audit stamps or mutating nodes fails: 1. The transaction must immediately execute tx.Rollback(ctx). 2. Any error returned by tx.Rollback must be joined with the primary failure via errors.Join(primaryErr, rollbackErr). 3. The combined error must be propagated to the caller without proceeding to subsequent steps.

Rule 2: Synchronous Status Transition Integrity

  • Status transitions on tasks and kernel entities must never discard mutation errors.
  • If updating task status to in_progress, blocked, complete, or failed fails, the execution loop must abort or surface the error, rather than continuing as if the transition succeeded.

Rule 3: Storage Lock Timeouts Must Fail Closed

  • When acquiring shared or exclusive locks (e.g. concurrency.WithLockTimeout, concurrency.WithRLockTimeout), lock timeouts must return explicit errors.
  • Cache loading or saving operations must never return true, nil or silent success when lock acquisition times out.

3. Verification

Verified by automated test suites:

  • cmd/zqk/agent/sync_loop_test.go (TestApplyStateMutation_ErrorPropagation, TestSyncLoop_MaxVerificationAttempts)
  • pkg/storage/reverse_reference_index_test.go (TestReverseReferenceIndex_SaveCache_LockContention_PropagatesError, TestReverseReferenceIndex_GetDependentsWithError_Contention)