Initial server source import

openspec/changes/add-worker-operator-experience/specs/worker-diagnostics/spec.md

@@ -0,0 +1,86 @@
+## ADDED Requirements
+
+### Requirement: Unified versioned diagnostic envelope
+Worker scan errors, provider failures, process failures, local exceptions, timeouts, prebundle failures, and assignment expiry context SHALL use one versioned diagnostic envelope with independent phase, kind, category, stable code, summary, retryability, attempt, timestamps, and optional HTTP/process/exception material.
+
+#### Scenario: Provider returns an HTTP error
+- **WHEN** a provider operation receives an unsuccessful HTTP response
+- **THEN** the diagnostic SHALL identify the phase, provider operation, HTTP status/content type, stable category/code, retryability, and captured response material
+
+#### Scenario: Scanner process fails
+- **WHEN** a scanner process exits unsuccessfully or is terminated at its deadline
+- **THEN** the diagnostic SHALL identify its process result, timeout/signal state, phase, stable category/code, and captured log material
+
+#### Scenario: Assignment expires without a worker result
+- **WHEN** the server expires an unresolved assignment
+- **THEN** it SHALL create or expose a diagnostic describing assignment expiry and the last accepted progress phase without claiming a scanner error occurred
+
+### Requirement: Diagnostic fidelity and explicit transformation
+Captured body and log bytes SHALL be preserved without silent semantic rewriting. Every size limit, encoding conversion, or truncation SHALL record original bytes, stored bytes, content hash, encoding, and truncation state.
+
+#### Scenario: Text body fits the bound
+- **WHEN** a captured provider response body fits the configured diagnostic body bound
+- **THEN** the transmitted diagnostic SHALL contain the complete captured text and SHALL mark it untruncated
+
+#### Scenario: Body exceeds the bound
+- **WHEN** captured body bytes exceed the transmitted bound
+- **THEN** the diagnostic SHALL carry the bounded material plus original/stored sizes, full captured-content hash when available, and `truncated=true`
+
+#### Scenario: Body is not text
+- **WHEN** captured diagnostic body bytes are not valid text in the declared encoding
+- **THEN** the envelope SHALL use an explicit binary encoding representation and SHALL preserve the same transformation metadata
+
+### Requirement: Bounded diagnostic transport
+The protocol SHALL enforce deterministic per-body, per-log, per-envelope, diagnostic-count, and aggregate diagnostic bounds while rejecting envelopes whose declared and actual sizes disagree.
+
+#### Scenario: Accepted bundle contains diagnostics
+- **WHEN** a worker uploads a result bundle with diagnostic frames within all bounds
+- **THEN** bundle acceptance and ingestion SHALL validate and persist each diagnostic idempotently with the scan
+
+#### Scenario: Diagnostic aggregate exceeds its limit
+- **WHEN** a bundle or terminal report exceeds a diagnostic count or byte limit
+- **THEN** the API SHALL reject it with a stable protocol error and SHALL NOT partially persist diagnostics
+
+### Requirement: Prebundle and accepted-result parity
+The same diagnostic envelope SHALL be usable in prebundle terminal reports and accepted scan-result bundles, with only transport-size profiles differing.
+
+#### Scenario: Worker storage fails before bundle creation
+- **WHEN** the worker cannot create a result bundle
+- **THEN** its terminal report SHALL include a diagnostic envelope rather than replacing the exception with one generic fixed detail string
+
+#### Scenario: Scan returns errors in a valid bundle
+- **WHEN** scanning completes with structured errors and a valid bundle
+- **THEN** those errors SHALL be represented as diagnostics attached to the ingested target scan and SHALL remain distinct from assignment transport outcome
+
+### Requirement: Deterministic diagnostic identity
+Each diagnostic SHALL have a deterministic UID derived from its canonical identity and content so retries and replay cannot create duplicates.
+
+#### Scenario: Accepted upload is replayed
+- **WHEN** an identical accepted result bundle is uploaded again
+- **THEN** the server SHALL return the durable receipt and SHALL NOT insert duplicate diagnostic rows
+
+#### Scenario: Same code occurs twice in one assignment
+- **WHEN** two distinct occurrences share category and code but differ in occurrence identity or content
+- **THEN** both SHALL be retained as distinct diagnostics with stable UIDs
+
+### Requirement: Local diagnostic archive
+The worker SHALL retain a queryable local JSON diagnostic envelope and optional body/log artifacts per assignment, with configurable age/byte rotation and explicit artifact-availability state in history.
+
+#### Scenario: Operator opens a local diagnostic
+- **WHEN** `truf-worker history` or `logs` selects a retained diagnostic
+- **THEN** the worker SHALL present the canonical envelope and exact paths/availability of its body and log artifacts
+
+#### Scenario: Artifact rotates out
+- **WHEN** a body or log artifact is removed by configured local rotation
+- **THEN** terminal history SHALL remain and SHALL state that the artifact is no longer locally retained
+
+### Requirement: Orthogonal error taxonomy
+The diagnostic model SHALL keep phase, kind, broad category, stable code, retryability, assignment outcome, and scan outcome as separate dimensions.
+
+#### Scenario: Accepted scan has provider errors
+- **WHEN** a result bundle is durably accepted but the scan outcome is `error`
+- **THEN** the assignment outcome SHALL remain `accepted`, scan outcome SHALL be `error`, and provider diagnostics SHALL retain their own categories/codes
+
+#### Scenario: Assignment expires
+- **WHEN** an assignment expires before bundle acceptance
+- **THEN** assignment outcome SHALL be `expired`, scan outcome SHALL be unavailable, and the expiry diagnostic SHALL not be categorized as a provider scan failure