[caballeto]

Summary

Two follow-ups to #160:

1. R16 deprecation window. On an uptime monitor, monitors.test(id) keeps returning the probe result until 2027-01-31, as 1.12 did, with a one-time DeprecationWarning pointing to monitors.probe(id). From that date it raises ValidationError USE_PROBE. This matches the amended doc 42 R16 and sdk-js.
2. include (W0-13). Explicit include paths (files nothing imports, such as fixtures/order.json) are sent as CreateBundleRequest.include on a JSON upload, or as the include query parameter on a zip upload. The server then keeps them in the closure.

The spec is generated from mono #1436 (feat/bundle-include, head 9405da4), including its docs/contracts/bundle-vectors.json. It will be identical once #1436 merges.

What's covered (doc 42 map)

• §2 R16. test() returns MonitorTestOutcome = RunDto | MonitorTestResultDto. devhelm.is_run() is a TypeGuard[RunDto] that narrows it, mirroring sdk-js isRun.
  • Only a 200 is treated as a probe result. Any other status that isn't 202 is refused.
  • From 2027-01-31, USE_PROBE carries details.passed, as in sdk-js.
• §5.3 / D-12, W0-13.
  • include adds files to the default set and names them to the server.
  • In-memory {entrypoint, files, include} is supported.
  • An include path that names no file is refused with MONITOR_PACKAGE_PATH_INVALID, field include[i], as the server does.
• §5.5.2. All 12 conformance vectors are checked:
  • the upload digest, and the closure digest over the server's file list;
  • the in-memory form carries the include list;
  • the refusal code and field for the symlink and include-missing vectors;
  • the import-outside-set vector is checked only for its code, because the include-set client never parses imports.
• Async. AsyncDevhelm gets both changes; it is generated from the same source.

Tests

• Unit: 1137 passed, 10 skipped (live tests skip without a stack). mypy --strict, ruff check/format and the unasync --check freshness check are clean.
• New tests:
  • sync and async probe-with-warning, and USE_PROBE after the date (clock patched);
  • is_run narrowing;
  • an unexpected status is refused;
  • fixtures/order.json ships from disk and appears in include;
  • zip uploads send repeated ?include= parameters;
  • no include is sent when none is given.
• Real-API matrix: not re-run on this branch, because the shared test API on :8081 was down. The last matrix run (Wave 0 stack, before the include change) gave 9 passed, 1 skipped. See "Not in this PR".

Self-review

Sonnet reviewer on the final diff: 2 P0s, both fixed.

• typing_extensions was imported but not declared as a dependency. It is now declared, and TypeGuard/NotRequired come from typing.
• Any non-202 status was being treated as a probe result. Now only 200 is.

P1s also fixed:

• the removal date has a single source;
• the refusal field is asserted on every vector;
• async tests cover the deprecation path;
• zip include is tested;
• TypeAlias is annotated.

Review follow-ups:

• P1: add @overloads on test() that narrow to RunDto when code= is given.
• P1: the stacklevel of the deprecation warning points one frame off under asyncio.
• P2: details.passed on USE_PROBE is undocumented beyond sdk-js parity.

Deviations from doc 42

• None for R16 (amended). AssertionTestResultDto is unchanged; that was noted in feat: synthetics surface, AsyncDevhelm and typed errors (doc 42 §9) #160.

Not in this PR

• Real-API re-run of the matrix with run admissions opened (mono #1435 open-synthetics-admissions): the shared test API on :8081 was down. To rerun:

  DEVHELM_E2E_API_URL=http://localhost:8081 DEVHELM_API_TOKEN=devhelm-dev-token DEVHELM_ORG_ID=<seed> DEVHELM_WORKSPACE_ID=<seed> uv run pytest tests/test_synthetics_live.py
  

• Live check of include-kept against the server: this needs a stack running #1436.
• Release: left to the user.

How to verify locally

uv sync
make lint && make typecheck && make test

🤖 Generated with Claude Code