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,120 @@
+## ADDED Requirements
+
+### Requirement: Protocol 2 source capabilities
+Protocol-2 worker packages SHALL advertise explicit source, worker-platform, and planning-kind capabilities for GitLab, DockerHub, and HuggingFace, and the server SHALL issue work only when the selected package supports the complete assignment capability.
+
+#### Scenario: Compatible package requests work
+- **WHEN** a protocol-2 package advertising the required capability requests a supported target
+- **THEN** the server may create an assignment using that capability
+
+#### Scenario: Package lacks planning capability
+- **WHEN** a package advertises the source but not the required planning kind
+- **THEN** the server rejects the claim without reserving a target
+
+#### Scenario: Package advertises unknown capability
+- **WHEN** a package manifest contains an unknown source, platform, or planning kind
+- **THEN** package validation fails closed
+
+### Requirement: Canonical multisource execution plans
+The server SHALL create and validate immutable execution snapshots using `exact_git_v1` for GitLab, `docker_direct_v1` for DockerHub, and `huggingface_space_v1` for HuggingFace.
+
+#### Scenario: GitLab assignment is issued
+- **WHEN** a GitLab target is claimed
+- **THEN** the assignment binds the existing exact commit and Git scan plan under `exact_git_v1`
+
+#### Scenario: DockerHub assignment is issued
+- **WHEN** a public DockerHub target is claimed
+- **THEN** the assignment binds an immutable digest reference under `docker_direct_v1` and does not depend on a mutable tag
+
+#### Scenario: HuggingFace assignment is issued
+- **WHEN** a public HuggingFace Space is claimed
+- **THEN** the assignment binds its canonical Space identifier under `huggingface_space_v1`
+
+#### Scenario: Snapshot shape does not match source
+- **WHEN** an execution snapshot's source, worker platform, or planning kind combination is invalid
+- **THEN** the server and worker reject it before scanner execution
+
+### Requirement: Fenced assignment authority for every source
+Every supported source assignment SHALL bind one user, device, target, fixed expiry, immutable execution snapshot, result reservation, and result bundle identity using the existing PostgreSQL authority model.
+
+#### Scenario: Lost claim response is retried
+- **WHEN** the server committed an assignment but the worker did not receive the response
+- **THEN** retrying the same admission request returns the same assignment and immutable execution snapshot
+
+#### Scenario: Stale worker uploads
+- **WHEN** a worker uploads with an expired, replaced, or mismatched reservation token
+- **THEN** the server rejects the upload without changing queue or bundle authority
+
+#### Scenario: Valid result commits
+- **WHEN** a valid assigned worker uploads and finalizes its bundle
+- **THEN** ingestion commits the queue result and downstream projection work exactly once
+
+### Requirement: Eligible source fallback
+The assignment service SHALL try other eligible configured sources when one supported source has no claimable target, while still issuing at most one assignment for an admission request.
+
+#### Scenario: Initially selected source is empty
+- **WHEN** the first eligible source has no claimable target and another eligible source does
+- **THEN** the same claim request may receive one assignment from the other source
+
+#### Scenario: All eligible sources are empty
+- **WHEN** no compatible source has a claimable target
+- **THEN** the claim returns no work and creates no reservation
+
+### Requirement: Legacy protocol-1 completion compatibility
+After protocol-2 cutover, the server SHALL stop issuing new claims to protocol-1 packages but SHALL continue status, terminal report, upload, receipt replay, and immutable snapshot reconciliation for already-issued protocol-1 assignments until they resolve or expire.
+
+#### Scenario: Protocol-1 package requests a new claim
+- **WHEN** a legacy GitHub/GitLab-only package requests new work after cutover
+- **THEN** the server returns an incompatibility response and creates no assignment
+
+#### Scenario: Existing protocol-1 assignment uploads
+- **WHEN** a legacy worker uploads a valid result for an assignment issued before cutover
+- **THEN** the server accepts and ingests it under its original immutable authority
+
+#### Scenario: Legacy snapshot is reconciled
+- **WHEN** the server reconstructs a lost response for an existing protocol-1 assignment
+- **THEN** it reads the original snapshot without rewriting it into protocol 2
+
+### Requirement: DockerHub end-to-end canary
+The rollout SHALL prove a bounded DockerHub `search -> enqueue -> claim -> scan -> upload -> ingestion -> projection` cycle using a public image resolved to an immutable digest before broader new-source enablement.
+
+#### Scenario: DockerHub canary succeeds
+- **WHEN** a canary producer discovers the configured public image and a compatible worker processes it
+- **THEN** the target reaches database-committed ingestion and projection under one fenced assignment
+
+#### Scenario: Mutable tag changes during canary
+- **WHEN** the discovered tag changes after queue admission
+- **THEN** the worker still scans the immutable digest bound in its assignment
+
+#### Scenario: Registry credentials would be required
+- **WHEN** the DockerHub canary target cannot be scanned without private registry credentials
+- **THEN** the worker returns a bounded inaccessible-provider result, the server applies its declared retryability, and no discovery or registry credential is transferred in the assignment
+
+### Requirement: HuggingFace remote processing
+The system SHALL support the same fenced claim-to-ingestion lifecycle for public HuggingFace Spaces without invoking the scanner on the server.
+
+#### Scenario: Public Space completes
+- **WHEN** a compatible worker claims and scans a public HuggingFace Space
+- **THEN** its result is uploaded, ingested, and projected under the bound assignment
+
+#### Scenario: Space is inaccessible without worker credentials
+- **WHEN** a tokenless worker cannot read a claimed HuggingFace Space because its repository is private, protected, removed, or otherwise unavailable
+- **THEN** it returns a non-retryable inaccessible result, the server does not retry that target, and the server discovery token is never exposed
+
+### Requirement: Worker-authoritative provider access
+The server SHALL validate canonical target and assignment authority but SHALL treat worker execution as the final provider-access check. A source SHALL NOT require a per-target server access probe, durable public-access proof, proof-freshness state, broad child-environment credential scrubbing, credential sandbox, or post-hoc redaction pipeline unless the operator separately approves an explicit OpenSpec requirement and implementation task.
+
+#### Scenario: Provider accessibility changes after discovery
+- **WHEN** a canonical target becomes inaccessible before worker execution
+- **THEN** the worker returns the source's bounded permanent or retryable provider-failure result and the server settles or retries it according to that result
+
+#### Scenario: Another source adapter is proposed
+- **WHEN** implementation would add preventive access proof or source-specific security infrastructure beyond the assignment's declared fields
+- **THEN** implementation pauses until the operator approves a dedicated requirement and task
+
+### Requirement: Credential and result secrecy
+Provider credentials, worker device tokens, authorization headers, and result contents SHALL NOT appear in operation status, audit records, Supervisor snapshots, or routine assignment logs.
+
+#### Scenario: Assignment logging occurs
+- **WHEN** any supported source assignment is created, retried, rejected, or completed
+- **THEN** logs identify bounded source and authority metadata without credential values or result payload bytes