Thermos Review Constraints
Relevant source files
The following files were used as context for generating this wiki page:
Thermos Review Constraints define the advisory correctness and quality standards for Pull Requests (PRs) within the Spotty repository. The OpenCode Thermos review provides a single advisory review when a PR becomes ready, focusing on architecture, safety, and project-specific invariants.
These constraints ensure that experimental software built on reverse-engineered interfaces maintains strict account safety and binary integrity. The review covers Swift concurrency, native macOS behavior, and the narrow integration between the Rust playback engine and the AVFoundation frontend.
Sources: CONTRIBUTING.md:7-8, AGENTS.md:6-12
Correctness and Safety Constraints
Spotty enforces strict correctness rules to protect user sessions and ensure playback reliability. Correctness is measured by automated gates that validate binary signatures, memory safety, and account handling.
Concurrency and Thread Safety
The project treats Swift concurrency diagnostics as correctness failures.
- You must preserve explicit isolation, ownership, and cancellation.
- Do not use
nonisolated(unsafe), mutable globals, or broad singletons to bypass compiler checks. - Detached task lifetimes are prohibited unless explicitly authorized for a specific architectural need.
Sources: AGENTS.md:50-55
Playback Engine Integrity
The playback engine uses a pinned Rust/librespot leaf. The review enforces the following constraints on the engine:
- ABI Signatures: The C header symbols must match the static library exports exactly.
- Fixture Validation: Each C declaration must match the canonical function type defined in the Rust ABI fixture.
- Digest Pinning: Static library names must include the engine input digest and library digest to ensure content-addressed integrity.
Sources: Scripts/check.sh:110-140, Backend/spotty-playback/validate-xcframework.sh:65-75
Quality and Maintenance Constraints
Quality constraints prevent technical debt and ensure that the codebase remains navigable for both human and automated agents.
Documentation Standards
- You must update the
AGENTS.mdchain for any non-obvious project constraints. - Documentation should name the component and state its action using active verbs.
- Omit task history, obvious code narration, and repeated rationale.
- Discoverable instructions are stored in the nearest
AGENTS.mdfile relative to the affected path.
Sources: AGENTS.md:70-75, AGENTS.md:85-90
Code Quality Gates
Automated scripts enforce the following quality standards:
- Swift Formatting: PRs fail on Swift format drift.
- Rust Warnings: The Rust backend must be warning-clean according to
cargo clippy. - Dead Export Detection: Header symbols not consumed by
PlaybackCore.swiftare treated as errors to prevent binary bloat.
Sources: Scripts/check.sh:30-35, Scripts/check.sh:175-185
Orchestration and Promotion Constraints
The Thermos review monitors the orchestration of CI candidates and the promotion of playback artifacts.
CI Job Requirements
A candidate for promotion must pass a specific set of required jobs. If any required job fails, the candidate is rejected.
| Job Name | Purpose |
|---|---|
| Rust checks | Validates engine formatting, clippy, and tests. |
| Candidate Swift debug | Verifies boundary tests in debug configuration. |
| Candidate Swift release | Verifies app packaging in release configuration. |
Sources: Scripts/playback_promotion.py:25, Scripts/check.sh:220-250
Artifact Validation Flow
The promotion script ensures that artifacts published to the repository are identical to those tested in CI.
This diagram shows the sequence of checks required to promote a playback artifact from a CI run to a release tag. Sources: Scripts/playback_promotion.py:30-80
Provenance Constraints
Every playback XCFramework must contain a spotty_playback_provenance.json file. This file must record:
- The
engineInputDigestderived from Rust source inputs. - The
librarySHA256of the compiled static archive. - The
canonicalHeadersSHA256of the C interface. - A boolean
sourceDirtyflag indicating if the build included uncommitted changes.
Sources: Backend/spotty-playback/build-xcframework.sh:130-160, Backend/spotty-playback/validate-xcframework.sh:125-140
PR Acceptance Criteria
A PR is only considered ready for merge when it satisfies the advisory Thermos review and the repository gates.
This sequence diagram illustrates the interaction between the developer, the advisory review system, and the automated CI runner. Sources: CONTRIBUTING.md:16-25
Summary of Review Gates
The following table summarizes the technical checks enforced during the review process.
| Category | Requirement | Implementation |
|---|---|---|
| Correctness | No nonisolated(unsafe) | Swift Compiler Diagnostics |
| Integrity | Provenance/Digest Match | validate-xcframework.sh |
| Consistency | C Header Symbols == Exports | check.sh using nm and clang |
| Deployment | macOS 15.0+ | otool inspection of LC_BUILD_VERSION |
| Legal | Discoverable License Texts | generate-playback-notices.py |
Sources: Scripts/check.sh:120-150, Backend/spotty-playback/validate-xcframework.sh:100-115, Scripts/generate-playback-notices.py:200-220