> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Strands

## `needs_regeneration`

When active evidence is withdrawn but other evidence remains, the strand is marked `needs_regeneration = true` and a system revision with the regeneration pending placeholder text is appended. No automatic regeneration job runs yet; facilitators must publish a new person revision when copy should be restored.

`needs_regeneration` is cleared when a person appends a revision, or when a non-withdrawal system revision is appended. Withdrawal-driven system revisions (`evidence_withdrawn_redacted`, `evidence_withdrawn_needs_regeneration`) do not clear the flag.

Strands with `needs_regeneration` are excluded from enrichment match pools until the flag is cleared.

## Revision redaction

Historical `strand_revisions` rows are append-only. Withdrawal redaction updates run through the `redact_strand_revision_for_withdrawal(revision_id, evidence_id)` database function. It redacts a revision only when the given evidence row belongs to the same strand and is in the `withdrawn` or `erased` state.

Whenever active evidence is withdrawn or erased, every unredacted revision of the strand is redacted, not only the revision the evidence points at. Enrichment attaches and person edits create later revisions that copy the earlier text without being linked to the evidence, so all of them are treated as derived from it. The live draft is redacted when its text reflects the withdrawn quote.

The function is `SECURITY DEFINER` with a fixed `search_path`, and `EXECUTE` is revoked from `PUBLIC`. The application connects as the owning role, so no further grant is needed; if a separate application role is introduced, grant `EXECUTE` to it explicitly. The `kair.strand_redaction_guard` setting checked by the append-only trigger can be set by any session, so it guards against accidental updates rather than acting as a privilege boundary.

## Session locking

Withdrawal and erasure take an exclusive transaction-scoped advisory lock on the session (`lock_session_strands_exclusive`). Live draft persistence and the enrichment transactions take the shared form of the same lock (`lock_session_strands_shared`) before reading withdrawn segment ids, so evidence from a segment cannot be inserted after a concurrent withdrawal of that segment has committed.

Proposed relations are inserted inside a savepoint, so a relation refused by the cross-workspace checks or the database trigger is logged and skipped without aborting the surrounding transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.