fix(starter): refuse before writing what it can name, and let the fleet skip a run that never wrote

[krzysztof-smartdataengines]

Summary

The Weather starter now refuses, before writing anything, the failures it can name: a binding's
driver that cannot be imported, and a bootstrap map that does not load. A run that failed before its
first write no longer stops every later fleet run in its directory.

Found on an installed acceptance

Both were found building the installed Weather acceptance for storage and time telemetry. The
environments there were built by a script that left out what docs/weather-starter.md tells a
customer to install: the signed extra, and pg for Node.

• setup without the signed extra. The CLI answered {"error": "MapError", "message": "Operation incomplete. Inspect local state and the run report before retrying; uncertain writes must not be replayed."}. Nothing had been written: bootstrap() refuses before setup opens its
  transaction. The one sentence that said what to install was hidden: "this map is signed, but
  signature verification needs the 'signed' extra".
• A TypeScript run without pg. The first measureStorage() could not open a session. The run
  retried a missing package for its whole 10-second recovery budget (185 retries), exited with "The
  local operation did not complete", and left a report with status: incomplete, no pending range
  and no row. After that, --workload fleet refused in that directory ("every earlier run of this
  project must be complete; inspect the unfinished run first"). No command could settle a run that
  wrote nothing.

What changed

• setup, doctor and run (Python) and run (TypeScript) import each binding's driver
  before writing anything, and refuse naming what to install:

  • in Python, pip install 'smart-data-engine-sdk[postgres]' or [clickhouse];
  • in Node, npm install pg.

  The import is the adapter's own, so a module that is present but cannot load counts as missing
  too. A run refuses before its report exists, so it leaves no unfinished run behind.

• setup says why the bootstrap's map does not load
  (The bootstrap's map does not load: ...). The reason is about the map, never about a credential.
  A public key that is not base64 is refused as an invalid key configuration.

• The fleet skips an earlier run that failed before its first write, in both languages: status
  incomplete, no pending range, and zero acknowledged, uncertain-verified and verified rows. A
  run records each batch before writing it, so such a run wrote nothing. The fleet still refuses:

  • a run that may have written (a pending batch, or any acknowledged or verified row);
  • a run still marked running, which may be interrupted or still going;
  • a report without these counters.

• docs/weather-starter.md says both.

Tests

• Python (test_demo_starter.py):

  • the fleet skips a run that failed before writing, and still refuses seven variants that may
    have written;
  • setup names the missing signed extra and writes nothing;
  • a key that is not base64 is refused;
  • setup and run refuse a missing driver before writing, and the run leaves no runs/
    directory;
  • the check imports each dialect's module once.

  All of them were red on main for the stated reason:

  • the fleet refused;
  • the raw MapError and binascii.Error reached the caller;
  • setup refused only at allocation, after writing its files;
  • a session opened without a driver.

• TypeScript (weather.test.ts):

  • the fleet rule;
  • requireDrivers checks pg only for a PostgreSQL binding;
  • a run without pg refuses before its report exists and before any session. On main this run
    sat in the retry loop until the test timed out.

• make check with both live engines on the head: ruff, mypy, Python 2081 passed and 10 skipped (the orderbook slice), TypeScript 999 passed.

• Mutations on the committed branch head: 10 killed and 2 controls survived. The killed mutations
  cover the fleet rule in both languages (skip removed, a running run skipped, acknowledged rows
  ignored), the map and key refusals, each driver check removed, and the TypeScript check applied to
  every dialect.

🤖 Generated with Claude Code