fix(knowledge): preserve live document jobs during recovery

[waleedlatif1]

Summary

• Keep document recovery from replacing jobs that are still queued, delayed, waiting, or running. Preserve live outbox continuations and defer recovery when queue status cannot be verified.
• Recheck the inspected generation under lifecycle locks before recovery, with bounded queue lookups and recheck backoff.
• Report indexed and skipped processing outcomes separately, without retrying harmless skips. Permissions, billing, processing concurrency, and schemas are unchanged.

Type of Change

• Bug fix

Testing

• 1,327 document, connector, and worker tests passed; one existing skip.
• 30 disposable PostgreSQL integration tests passed, including queued-job preservation in both recovery paths, generation races, outbox continuations, lifecycle locking, and existing billing/search recovery.
• App type-check, repository lint, all 47 audits (including API boundary validation), block registry audit, and docs manifest check passed.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
docs	Skipped		Sep 19, 2026 12:04am UTC

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the recovery changes consistently preserve live work and fence stale queue observations before mutation.

Summary

This PR hardens stored-document recovery so it does not replace processing generations that still have live queue or outbox work.

• Inspects Trigger run state before admitting stale documents for recovery and defers unverified generations.
• Rechecks queue-generation metadata under lifecycle locks before replacing a generation.
• Protects pending and processing outbox continuations from recovery.
• Distinguishes successfully indexed documents from harmless skipped processing outcomes.
• Adds unit and integration coverage for live jobs, queue lookup failures, generation races, continuations, and both recovery paths.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Select stale document candidates] --> B{Active outbox continuation?}
  B -->|Yes| C[Leave generation unchanged]
  B -->|No| D{Trigger available?}
  D -->|No| E[Apply existing recovery policy]
  D -->|Yes| F[Inspect live Trigger runs]
  F -->|Live run found| G[Set recovery recheck delay]
  F -->|Lookup failed or timed out| G
  F -->|No live run| H[Candidate considered abandoned]
  H --> I[Acquire knowledge-base and connector lifecycle locks]
  I --> J{Generation metadata still matches?}
  J -->|No| C
  J -->|Yes| K[Create replacement token and outbox event]
  K --> L[Processing worker claims generation]
  L --> M{Index commit accepted?}
  M -->|Yes| N[Return indexed outcome]
  M -->|No| O[Return harmless skipped outcome]

Loading

_{Reviews (1) · Last reviewed commit: "fix(knowledge): preserve live document j..."}