truf-server/openspec/changes/stabilize-and-widen-scanner-coverage/specs/scanner-runtime-stability/spec.md

ADDED Requirements

Requirement: Durable Asynchronous Result Handoff Supersedes Source Publication

PostgreSQL SHALL be the sole result authority. A fair global permit count of three SHALL end after a pre-reserved result bundle is fsynced and atomically renamed on S:, without covering database ingest, JSONL projection, or keychecks.

Scenario: Projector or database is blocked after bundle handoff

• WHEN a source completes the durable ready rename
• THEN its scan permit SHALL be released while the bundle remains recoverable and downstream backlog applies capacity-based admission pressure

Requirement: Correctness Does Not Depend On Recycling

The runtime SHALL NOT use GC trimming, source lifetime limits, private-memory restarts, periodic recycling, reduced concurrency, or time-based restarts to preserve correctness.

Scenario: Runtime memory grows after warmup

• WHEN a managed process reports increasing private memory
• THEN admission and durable queue capacity SHALL provide backpressure without recycling the process or reducing the configured three scan permits

Requirement: Resilient Runner State Writes

The scanner SHALL persist runner state using a unique temporary file per write attempt and SHALL retry replacement when the operating system reports a transient file access error.

Scenario: Concurrent state read during write

• WHEN a supervised source writes runner_state_<source>.json while supervisor or dashboard reads the same state file
• THEN the source process SHALL retry the replacement and continue without crashing when the file becomes available within the retry window

Scenario: Persistent state write failure

• WHEN the state file cannot be replaced after the bounded retry window
• THEN the source process SHALL surface the final write error instead of silently discarding state changes

Requirement: State Writes Avoid Shared Temp Path Contention

The scanner SHALL avoid using a single shared .tmp path for repeated state writes from supervised processes.

Scenario: Multiple state write attempts overlap

• WHEN two state write attempts occur close together for the same state file
• THEN each attempt SHALL use a distinct temporary file path before replacing the final state file

Requirement: Restart Noise Reduction

The supervisor SHALL no longer restart sources due only to transient state-file replacement races that resolve within the retry window.

Scenario: GitLab state replacement race resolves

• WHEN the GitLab source hits a transient Windows file lock while saving state
• THEN the source SHALL complete the state save after retry and its up timer SHALL not reset because of that transient race