Critical lesson from 2026-02-05: GitLab runs in Docker with SSH
mapped from host port 2222 to container port 22. Missing Port 2222
in SSH config causes SSH to hit host sshd instead of GitLab, leading
to fail2ban blocks and hours of debugging the wrong thing.
Signed: Agent Blackops
QR tests MUST use native language libraries, not qrencode CLI.
If the sandbox doesn't have the library, the test should FAIL
honestly so we know what to fix in the sandbox image.
Also adds CLAUDE.md rule to prevent future attempts to replace
native library QR tests with CLI subprocess calls.
SCIENTIFIC INTEGRITY: Tests now retry transient errors (429, 5xx,
timeouts) with exponential backoff instead of falsely passing.
Prior to this fix, ~35% of 'passing' tests were masked failures.
Now tests will PASS (verified), FAIL (couldn't verify), or SKIP.
The CLI was using library-only types and functions (unsandbox_languages_t,
unsandbox_image_list_t, etc.) that are only available when UNSANDBOX_LIBRARY
is defined. This caused build failures when building as CLI.
Changes:
- Add static list_languages_cli() for CLI language listing
- Fix image list to parse JSON directly instead of using library types
- Fix spawn_from_image() call with missing bootstrap/network_mode args
- Fix image_publish/clone_image calls to use static functions
Also update CLAUDE.md with release/versioning documentation.
C SDK changes:
- Add #include un.h when building as library
- Export library functions: version, detect_language, hmac_sign, health_check
- Add NULL safety checks to wrapper functions
- Rewrite tests to call ACTUAL exported functions (no more local re-implementations)
- Tests now verify real HMAC-SHA256 against known test vectors
Documentation:
- Add SDK Testing Philosophy to CLAUDE.md
- Create docs/TESTING.md with unit/integration/functional test definitions
- Document the THREE testing levels required for all SDKs
- Explicitly forbid mocking and local re-implementation in tests
33 unit tests pass, testing real exported functions.
Add comprehensive testing infrastructure for UN clients:
1. Smart Change Detection (detect-changes.sh)
- Detects changes in BOTH root-level (un.py, un.go) AND clients/ directory
- Maps file extensions and directory names to languages
- Triggers test_all when infrastructure changes
2. Language-Specific CI Matrix (generate-matrix.sh compatible)
- Only runs tests for languages with changes
- Example: modify clients/python/ → pytest runs, Go/Ruby skipped
3. Testing Strategy Document (TESTING-STRATEGY.md)
- Complete testing matrix by language tier (compiled, interpreted, inception)
- Unit, integration, embedding, and parity tests
- Inception pattern for languages without local interpreters
- Common failures and fixes
- Rollout schedule for client/ migration
4. Makefile Targets
- 'make test-python', 'make test-go', etc. for local development
- 'make test-all' for comprehensive testing
- 'make test-integration' for API contract validation
- 'make test-ci-locally' to simulate CI pipeline
5. Updated CLAUDE.md
- Documents SDK architecture (in growth state)
- Explains three purposes: CLI, library, embeddable
- References TESTING-STRATEGY.md for details
This enables:
✓ Per-language testing (only run what changed)
✓ Local developer workflow (make test-LANG)
✓ 42+ language feature parity validation
✓ Cross-language integration testing
All 38+ implementations now support:
- session -f FILE: Upload files to /tmp/ in session container
- service -f FILE: Upload files to /tmp/ in service container
- service --bootstrap-file FILE: Read bootstrap script from file
- Update all un.* implementations to use HMAC-SHA256 signing
- Headers: Authorization (Bearer public_key), X-Timestamp, X-Signature
- Signature: HMAC-SHA256(secret_key, "timestamp:METHOD:path:body")
- Fix test suite issues (bash arithmetic, ES module compat, TCL shebang)
- Add CLAUDE.md with inception testing documentation
- Update README.md with HMAC auth and dependency table
- All 38 implementations pass inception test via un2
