Pipelines and transactions

Knowledge changes in batches: a single piece of work usually creates and updates several related entities at once. Kvendra groups those changes into a transaction (TXN) so they land together or not at all, and records every change in a typed, server-side changelog.

The transaction (TXN) flow

Changes are grouped into a transaction (TXN). The flow: create the TXN; for each phase, create entities carrying the txn id so the server forces them to ‘draft’ status; on success, activate the TXN so the drafts move to their terminal status; on failure, cancel the TXN so the drafts become ‘cancelled’. Before starting, you check for an interrupted TXN to avoid duplicates.

Naming and identifiers

Ids are stable and human-readable. PRJ-<PROJECT>, CMP-<PROJECT>-<COMP> and REL-<PROJECT>[-<COMP>]-<X.Y.Z> accept an explicit id. Every other type gets an auto id of the form <TYPE>-<PROJECT>[-<COMP>]-<6HEX>. Transaction ids look like TXN-<PROJECT>-<YYYYMMDD>-<NNN>. STD entities follow STD-<PROJECT>-<COMP?>-<TOPIC>.

Validation

The engine validates entity ids against the naming rules, validates relation targets, and enforces transaction state. Typical conflicts: a duplicate TXN (resolved by checking for an interrupted TXN first), or operating on an already-cancelled or already-completed TXN (re-read the state).

The lifecycle, step by step

1. txn_create        -> open a transaction, scoped to a project (and optionally a component)
2. entity_create     -> create entities carrying the txn id; the server forces them to "draft"
   entity_update      -> further edits stay inside the same transaction
3a. txn_activate      -> success: every draft moves to its terminal status
3b. txn_cancel        -> failure: every draft becomes "cancelled"

Drafts are invisible to normal reads until the transaction activates, so a half-finished pipeline never pollutes the knowledge base. The terminal status depends on the type: most land on active, an issue on open, a decision on accepted, a run on recorded.

The typed changelog

Every create and update is recorded by the engine itself — not by the caller — as a versioned history entry with the author, the trigger (often the transaction id), and a change summary. Because history is maintained server-side, it cannot be skipped or rewritten by a client, which is what makes the audit trail trustworthy.

Resilience

Before starting, a pipeline checks for an interrupted transaction so it does not open a duplicate. Operating on a transaction that is already cancelled or already completed is reported as a conflict, prompting the caller to re-read the current state rather than guess.