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,68 @@
+## ADDED Requirements
+
+### Requirement: Git scans are bound to an exact revision
+The system SHALL resolve a normalized ref and exact commit SHA for each claimed GitHub or GitLab repository before invoking TruffleHog and SHALL bind that immutable plan to the active reservation.
+
+#### Scenario: Repository search supplies no ref hint
+- **WHEN** a claimed repository came from metadata search without an exact ref
+- **THEN** the system resolves the provider's current default branch and its exact head SHA
+
+#### Scenario: Discovery supplies an exact ref hint
+- **WHEN** an event-backed target includes a valid branch ref
+- **THEN** the system resolves and binds that specific ref instead of substituting the default branch
+
+#### Scenario: Revision lookup fails
+- **WHEN** the provider API cannot return a valid ref and commit SHA
+- **THEN** the claim receives a bounded retryable source failure and no exact coverage state advances
+
+### Requirement: Git updates scan every newly introduced commit
+The system SHALL scan the exact claimed head after the last successfully covered head for the same ref and SHALL NOT apply rolling age or maximum-depth limits to that incremental range.
+
+#### Scenario: Same ref advances
+- **WHEN** ref `R` was successfully covered at commit `A` and now resolves to descendant commit `D`
+- **THEN** the scan is pinned to `D` with `A` as its boundary and includes commits introduced between them
+
+#### Scenario: Secret is added and then deleted in the delta
+- **WHEN** one newly introduced commit adds a secret and a later newly introduced commit removes it
+- **THEN** both commits remain in scan scope even though the final filesystem snapshot is clean
+
+#### Scenario: Head is unchanged
+- **WHEN** the resolved head equals the successfully covered head for the same ref
+- **THEN** the system records an exact no-op without launching a redundant repository scan
+
+### Requirement: Git baseline and discontinuity handling remain pinned
+The system SHALL use a pinned bounded baseline for a first-seen ref or an unusable incremental base and SHALL identify that mode without claiming unbounded historical coverage.
+
+#### Scenario: Ref has no covered head
+- **WHEN** an exact ref is claimed without prior successful coverage
+- **THEN** the system scans its pinned head using the configured baseline depth bound and establishes that head as the future delta boundary on success
+
+#### Scenario: Covered base is unavailable
+- **WHEN** force push, ref recreation, or remote history removal makes the covered SHA unusable
+- **THEN** the system falls back to a pinned bounded baseline and records the continuity reset
+
+### Requirement: Git coverage advances only after successful fenced work
+The system SHALL update a queue row's covered ref and head only when successful ingestion applies a matching immutable reservation plan.
+
+#### Scenario: Exact scan succeeds
+- **WHEN** a pinned baseline or delta result is ingested with queue disposition `done` and its plan matches the active reservation
+- **THEN** the queue's covered ref and head advance to the claimed head
+
+#### Scenario: Exact scan fails or is deferred
+- **WHEN** execution fails, times out, loses its fence, or receives a deferred disposition
+- **THEN** the previously covered ref and head remain unchanged
+
+#### Scenario: Remote advances during a scan
+- **WHEN** a newer commit appears after the worker binds its immutable head
+- **THEN** successful completion advances coverage only to the bound head and leaves the newer update eligible for later discovery
+
+### Requirement: Exact Git scope is observable
+The system SHALL durably record the executed ref, head, base, scan mode, baseline bound, and whether immutable execution was preserved.
+
+#### Scenario: Operator inspects an incremental scan
+- **WHEN** an exact delta result is committed
+- **THEN** its normalized scan metadata identifies the covered range without exposing source credentials
+
+#### Scenario: Metadata discovery observes repository-level activity
+- **WHEN** no branch-specific event exists
+- **THEN** observability identifies the provider-resolved default-branch scope rather than implying coverage of every repository ref