Initial server source import

2026-09-30 20:30:56 +03:00
commit 170dd941b9
498 changed files with 261563 additions and 0 deletions
@@ -0,0 +1,40 @@
+## 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