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

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