Merge origin/main into feat/triage-with-api

BillGrieser-Antithesis · claude · BillGrieser-Antithesis · commit 8b9e0cb19057 · 2026-05-15T16:51:22.000-04:00
Brings in PRs #146 (snouty launch consistency), #147 (workload randomness guidance), #148 (interesting input values reference), #150 (workload fault-tolerance mindset), plus version metadata bumps. Conflict resolutions: - antithesis-debug/SKILL.md: version metadata — kept origin/main's freshest value (auto-regenerated anyway). - antithesis-launch/SKILL.md: kept feat/triage's more detailed webhook default rule (basic_test for docker-compose, basic_k8s_test for kubernetes) over main's older shorter rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,19 @@
 All notable changes to this project will be documented in this file. Entries
 are grouped by date (UTC) with newest first.
 
+## 2026-05-15
+
+- Make workload fault-tolerance mindset explicit ([PR #150](https://github.com/antithesishq/antithesis-skills/pull/150))
+
+## 2026-05-14
+
+- Add guidance for choosing interesting input values in workloads ([PR #148](https://github.com/antithesishq/antithesis-skills/pull/148))
+- Improve randomness usage when creating workloads ([PR #147](https://github.com/antithesishq/antithesis-skills/pull/147))
+
+## 2026-05-13
+
+- Use `snouty launch` instead of `snouty run` ([PR #146](https://github.com/antithesishq/antithesis-skills/pull/146))
+
 ## 2026-05-12
 
 - Recommend a simple property first ([PR #145](https://github.com/antithesishq/antithesis-skills/pull/145))
diff --git a/antithesis-debug/SKILL.md b/antithesis-debug/SKILL.md
@@ -8,7 +8,7 @@ description: >
   debugger (default) and the advanced notebook mode.
 compatibility: Requires agent-browser v0.23.4+ (https://github.com/vercel-labs/agent-browser).
 metadata:
-  version: "2026-05-13"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Multiverse Debugger
diff --git a/antithesis-documentation/SKILL.md b/antithesis-documentation/SKILL.md
@@ -3,7 +3,7 @@ name: antithesis-documentation
 description: Use Antithesis documentation efficiently for product, workflow, and integration questions. Prefer the snouty docs CLI when available, and otherwise request markdown versions of documentation pages directly.
 compatibility: Requires snouty (https://github.com/antithesishq/snouty).
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Documentation
diff --git a/antithesis-k8s-onboarding-assistance/SKILL.md b/antithesis-k8s-onboarding-assistance/SKILL.md
@@ -7,7 +7,7 @@ description: >
   what to keep, drop, or stub for testing, and produces structured
   questions for ops plus an escalation packet when stuck.
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis K8s Onboarding Assistance
diff --git a/antithesis-launch/SKILL.md b/antithesis-launch/SKILL.md
@@ -8,7 +8,7 @@ description: >
   run. This skill takes duration in minutes as input.
 compatibility: Requires docker (or podman) with compose and snouty (https://github.com/antithesishq/snouty).
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Launch
diff --git a/antithesis-query-logs/SKILL.md b/antithesis-query-logs/SKILL.md
@@ -7,7 +7,7 @@ description: >
   occur even without a preceding fault?).
 compatibility: Requires snouty (https://github.com/antithesishq/snouty) and agent-browser (https://github.com/vercel-labs/agent-browser).
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Logs Explorer
diff --git a/antithesis-research/SKILL.md b/antithesis-research/SKILL.md
@@ -5,7 +5,7 @@ description: >
   map the system, identify failure-prone areas and testable properties, and
   produce the research artifacts needed for workload and environment planning.
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Research
diff --git a/antithesis-setup/SKILL.md b/antithesis-setup/SKILL.md
@@ -6,7 +6,7 @@ description: >
   to submit your first Antithesis test run.
 compatibility: Requires docker (or podman) with compose and snouty (https://github.com/antithesishq/snouty).
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Setup
diff --git a/antithesis-skills-feedback/SKILL.md b/antithesis-skills-feedback/SKILL.md
@@ -7,7 +7,7 @@ description: >
   feedback on, any Antithesis skill. Does not auto-submit — presents the
   URL for the user to review.
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Skills feedback
diff --git a/antithesis-triage/SKILL.md b/antithesis-triage/SKILL.md
@@ -7,7 +7,7 @@ description: >
   details. Load after a run completes or when investigating a failure.
 compatibility: Requires snouty (https://github.com/antithesishq/snouty), and jq.
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Run Triage
diff --git a/antithesis-workload/SKILL.md b/antithesis-workload/SKILL.md
@@ -5,7 +5,7 @@ description: >
   assertions and test commands, then refine coverage after triage.
 compatibility: Requires snouty (https://github.com/antithesishq/snouty).
 metadata:
-  version: "2026-05-12 51c4311"
+  version: "2026-05-15 a0f67a6"
 ---
 
 # Antithesis Workload
@@ -104,6 +104,7 @@ Use the `antithesis-documentation` skill to access these pages. Prefer `snouty d
 | `references/component-implementation.md` | Implementing workload-side components or wrappers |
 | `references/assertions.md`               | Turning properties into SDK assertions            |
 | `references/test-commands.md`            | Writing commands and organizing test templates    |
+| `references/interesting-values.md`       | Choosing the value menu for the property under test |
 | `references/iteration.md`                | Improving coverage and assertions after triage    |
 
 ## Recommended Workflows
@@ -115,7 +116,9 @@ Use the `antithesis-documentation` skill to access these pages. Prefer `snouty d
 3. Read `references/component-implementation.md`
 4. Read `references/assertions.md`
 5. Read `references/test-commands.md`
-6. Implement the chosen property: assertions, test commands, and supporting code
+6. Read `references/interesting-values.md`
+7. Identify the property's value menu — boundary values plus configured-limit families. See `interesting-values.md` for the discovery process and worked examples
+8. Implement the chosen property: assertions, test commands, and supporting code
 
 ### Post-triage iteration
 
@@ -128,6 +131,7 @@ Use the `antithesis-documentation` skill to access these pages. Prefer `snouty d
 
 - Keep Antithesis-only code out of production paths. If you must touch shared code, make the change surgical and easy to wall off.
 - Prefer simple workload code over highly configurable abstractions.
+- Design workloads to be fault-tolerant. Unlike happy-path tests where errors signal bugs, workloads run under fault injection and concurrent activity — transient errors are expected, not exceptional. Make progress toward a goal rather than bail on the first failure.
 - Assume `antithesis-setup` has already made the system runnable in a mostly idle state; this skill owns what the workload does once the system is up.
 - Assume `antithesis-setup` has already installed the relevant SDK and added one minimal bootstrap assertion in the SUT. This skill owns the broader property catalog beyond that initial integration check.
 - Write test commands in the project's language, not Bash, so they can reuse the project's clients, helpers, and libraries.
@@ -149,7 +153,11 @@ Review criteria:
 - `Sometimes(true, ...)` assertions should be rewritten as `Reachable(...)`.
 - Assertion messages are unique across the touched code; no broad property is implemented by reusing one message at multiple unrelated callsites
 - Workload-only instrumentation was not used where surgical SUT-side assertions would provide materially better search guidance for rare, dangerous, or timing-sensitive internal states
+- Workload code makes progress toward stated goals under transient errors rather than bailing on first failure
+- The workload records both attempted and acknowledged operations so later assertions can check bounds (e.g., "counter changed by some value in `[acknowledged, attempted]`")
+- Where retries are used, they're consistent with the SUT's idempotency contract
 - `Reachable(...)` markers are attached to distinct outcomes or branch results, not redundant early path-entry locations on the same straight-line flow
+- For bounded inputs in test commands, draws come from property-specific value menus (boundary values for the input type plus configured-limit families from the property's code paths) rather than arbitrary ranges, or the test command documents that the menu axis is not applicable. See `interesting-values.md`.
 - Test commands exist under `antithesis/test/` and use valid prefixes (`parallel_driver_`, `singleton_driver_`, `serial_driver_`, `first_`, `eventually_`, `finally_`, `anytime_`)
 - Test commands are written in the project's language, not Bash, and reuse the project's clients and libraries where possible
 - No test command is responsible for Antithesis lifecycle signaling; `setup_complete` is emitted before test commands begin
diff --git a/antithesis-workload/references/assertions.md b/antithesis-workload/references/assertions.md
@@ -62,12 +62,26 @@ These fit properties where the individual boolean inputs matter on their own, fo
 
 When available, the SDK adds the named boolean inputs to assertion details under their names, which makes triage more informative than an anonymous combined expression.
 
+## Assert Bounds, Not Exact Values
+
+When a workload runs under fault injection, it can't directly observe everything that happened — requests fail in flight, acknowledgments are lost. The workload constructs bounds (see `component-implementation.md`, "Construct bounds, don't claim exact knowledge"), and the assertion's job is to check that observed state falls within those bounds.
+
+Use rich numeric assertions to encode the bound. If a workload sent 100 increment requests to a counter and 80 were acknowledged:
+
+- `AlwaysGreaterThanOrEqualTo(observed_delta, 80, "counter reflects all acknowledged increments")`
+- `AlwaysLessThanOrEqualTo(observed_delta, 100, "counter reflects no more than attempted increments")`
+
+Two assertions, not one, so triage shows which bound failed.
+
+Don't write `Always(observed_delta == 100, ...)` for the same property — that assertion will fire legitimately whenever the environment dropped requests, drowning real bugs in false positives.
+
 ## Anti-Rules
 
 - Do not use `Sometimes(true, ...)` in normal workload or SUT code. If the condition is constant true, use `Reachable(...)` instead.
 - Do not use `Sometimes(cond, ...)` when the only thing you care about is that execution hit a path. Use `Reachable(...)`.
 - Do not reuse one assertion message across multiple unrelated callsites. Every assertion message should be unique in the codebase.
 - Do not stack broad early `Reachable(...)` markers on a straight-line flow when a later, more specific outcome marker already proves the path was exercised.
+- Do not assert exact equality on values affected by transient errors. Use bounded assertions (see "Assert Bounds, Not Exact Values").
 
 ## Good and Bad Uses
 
@@ -103,6 +117,8 @@ Prefer outcome markers over earlier path-entry markers. If a later marker alread
 
 All randomness in test workloads must go through the Antithesis SDK's random module for deterministic replay. Whenever possible, the SUT should also leverage Antithesis randomness rather than using its own. If you are unable to use Antithesis provided randomness everywhere, the ability for Antithesis to quickly find bugs will be diminished.
 
+For guidance on which values to draw from — boundary values, configured-limit families — see `interesting-values.md`.
+
 ## Naming
 
 Give assertions clear, descriptive, unique names. These names appear in triage reports, so they should be immediately understandable and should localize one specific callsite or condition.
diff --git a/antithesis-workload/references/component-implementation.md b/antithesis-workload/references/component-implementation.md
@@ -21,7 +21,27 @@ This is the most open-ended part of the skill. Start with the simplest component
 
 ## Fault Tolerance in Workload Code
 
-If you are writing code that connects to a service over the network (e.g., test commands), ensure it handles all forms of temporary network faults. Read the Fault injection documentation to learn which faults your code needs to handle:
+Workloads run under fault injection. Transient errors are expected, not exceptional — the workload's job is to keep making progress toward its goal, not to bail on the first failure.
+
+### Design for goals, not procedures
+
+Write workload operations as loops that drive toward an objective, not fixed sequences of attempts. A workload that tracks "I tried 100 times" has nothing useful to assert against in a faulty environment; one that tracks progress against a goal can operate while the environment drops requests, partitions the network, or restarts nodes.
+
+### Construct bounds, don't claim exact knowledge
+
+Under fault injection a workload doesn't have perfect visibility — requests fail in flight, acknowledgments get dropped, clocks drift. The workload's job is to record enough of what happened to construct bounds the SUT must satisfy. Anything outside those bounds has probability zero of being correct, and that's how bugs surface.
+
+The most common way to construct a bound is to track attempts and acknowledgments separately. If a workload sends 100 increment requests to a counter and 80 are acknowledged, the counter must have changed by some number between 80 and 100 — unacknowledged requests may have succeeded anyway. A later read showing 75 or 120 is a bug, in the SUT or in the workload itself. A workload that records only "publish() called 100 times" has no bound to assert against.
+
+See `assertions.md`, "Assert Bounds, Not Exact Values" for how to express these bounds as assertions.
+
+### Retries are inputs to the system
+
+Retries are inputs the workload feeds into the SUT, not free additions — they shape what bugs you find. Retrying after an acknowledgment is lost can surface real idempotency bugs (good — that's a production scenario). Retrying past the SUT's idempotency contract creates faulty client behavior that produces false-positive assertion failures (bad). Decide what the SUT promises about idempotency before designing retry behavior.
+
+### Faults to handle
+
+Read the Fault injection documentation to learn what your code needs to tolerate:
 
 - Process kill/restart
 - Network partition (full and partial)
diff --git a/antithesis-workload/references/interesting-values.md b/antithesis-workload/references/interesting-values.md
@@ -0,0 +1,89 @@
+# Interesting Values
+
+Workload randomness has two axes:
+
+- The **shape axis** — how often each menu item is drawn (probabilities, action weights). Covered in `test-commands.md` under "Vary randomness across timelines."
+- The **menu axis** — what values are on the menu in the first place. Covered here.
+
+Both axes apply, and they compose: the menu axis decides what values can be drawn; the shape axis decides how often each is drawn.
+
+All draws in test commands must go through the SDK's random module so they replay deterministically. See `assertions.md`.
+
+## Why the menu axis matters
+
+If random draws come from arbitrary ranges — say, `randint(0, 1000)` — most draws land in the bulk of the range, far from any boundary. The corners where bugs hide get sampled rarely. A well-chosen menu replaces the arbitrary range with values that are interesting for the property under test: the boundaries of the input type plus property-specific values from the SUT.
+
+What counts as interesting depends on the property. The same value (a queue size of 100) matters intensely for a backpressure property and not at all for a serialization property. Don't try to enumerate interesting values system-wide. Find them per property, at implementation time.
+
+## Boundary values
+
+Every type has values where behavior changes — zero or empty, type minimums and maximums, off-by-one neighborhoods of those, type-specific edge cases (NaN for floats, encoding boundaries for strings, single-element collections, and so on). The property under test usually narrows or expands this set: a backpressure property cares about empty and capacity; an overflow property cares about MAX and MAX-1; a parser property cares about empty input and inputs at length-encoding boundaries. Include the boundaries that matter for the property's inputs and types, then add the property-specific values from discovery below.
+
+## Property-specific discovery
+
+For each property you're implementing, build the menu in this order:
+
+1. **Check the property's evidence file** at `antithesis/scratchbook/properties/{slug}.md`. Research may have already noted relevant configured limits and the code paths the property touches; if it has, use those as your starting point instead of re-scanning the SUT.
+
+2. **Scan SUT code paths the property touches**. The evidence file's "Relevant code paths" notes are the natural anchor; widen the scan only if those don't surface the limits. Look for configured limits (queue capacities, batch sizes, replica counts, retry counts), default values (timeouts, intervals, sizes), and threshold constants — the literal values that decide what happens.
+
+3. **Cross-reference config files and env vars**. Values in code are often parameterized; the runtime value depends on what the topology supplies. Check both.
+
+4. **Opportunistically scan recent bug fixes** in the touched paths. Fixes for boundary or off-by-one bugs often expose specific values worth including. If a quick scan surfaces something, include it; otherwise move on. No deep git archaeology.
+
+If discovery surfaces no configured limits — small or pure-logic properties — fall back to boundary values alone. That's still a valid menu. If limits are computed at runtime (e.g., `capacity = num_cores * 4`), build the family around the runtime value at the start of the timeline, the same pattern as swarmed configs (below).
+
+## Structure: families with neighborhoods
+
+Interesting values come in families, not flat lists. A configured value `N` parameterizes a family of values around it: `{N-1, N, N+1, ...}`. The family is named by the config it parameterizes. When the parameterizing value is a configured limit, this is a **configured-limit family** — the term used in the workload skill's self-review criterion.
+
+When the parameterizing config is itself on the shape axis (swarmed across timelines), the family rebuilds around whatever `N` is drawn for that timeline. The menu is a function of the swarmed parameters, not a static list.
+
+### Worked example 1: a timeout
+
+A property exercises a connection that times out after `CONNECT_TIMEOUT_MS = 5000`.
+
+- Boundaries: zero, one, max-of-i32
+- Family around N=5000: `{4999, 5000, 5001}` — just-under, at, just-over
+- Combined menu for connection-attempt durations: `{0, 1, 4999, 5000, 5001, 30000, MAX_I32}` — adding 30000 as a "well over" value, MAX_I32 as the upper boundary
+
+If `CONNECT_TIMEOUT_MS` itself is swarmed across `{100, 5000, 60000}`, the family rebuilds per timeline. A timeline that drew `CONNECT_TIMEOUT_MS = 100` uses the menu `{0, 1, 99, 100, 101, 600, MAX_I32}`.
+
+### Worked example 2: a queue capacity
+
+The property checks that a bounded queue rejects writes beyond its capacity `QUEUE_CAPACITY = 64`.
+
+- Boundaries: zero, one, max-of-usize
+- Family around N=64: `{63, 64, 65}` — just-under, at, just-over
+- Combined menu for number of writes to attempt: `{0, 1, 63, 64, 65, 128, MAX_USIZE}` — 128 as a "well over" value, MAX_USIZE as the upper boundary
+
+If the test swarms `QUEUE_CAPACITY` across `{1, 64, 4096}`, the family rebuilds per timeline. A timeline that drew `QUEUE_CAPACITY = 4096` uses the menu `{0, 1, 4095, 4096, 4097, 8192, MAX_USIZE}`.
+
+The same discovery process and family structure work for strings, collections, and other input types — the worked examples here are numeric for clarity.
+
+## Bridging to the shape axis
+
+Once the menu is built, the shape axis decides how often each menu item is drawn. See `test-commands.md`, "Vary randomness across timelines."
+
+A typical pattern:
+
+```
+# At the start of the timeline:
+queue_capacity = random_choice([1, 64, 4096])     # shape axis: vary the config
+menu = [0, 1, queue_capacity - 1, queue_capacity, queue_capacity + 1, 2 * queue_capacity]
+
+# Within the timeline:
+n_writes = random_choice(menu)                    # menu axis: draw from the menu
+```
+
+Both `random_choice` calls go through the SDK's random module (see `assertions.md`) so the timeline replays deterministically.
+
+## When the menu axis doesn't apply
+
+Some properties don't have bounded inputs worth thinking about — small fixed action vocabularies like `{create, drop}`, or properties without bounded inputs at all (pure reachability, fault-driven scenarios). For those, the menu axis is a no-op. Leave a brief comment in the test command, using the project's comment syntax, that says something like:
+
+```
+menu axis not applicable: action vocabulary is fixed at {create, drop}
+```
+
+Don't fabricate inputs to fill the section. "We considered the menu axis and it doesn't apply here" is exactly the signal self-review is looking for.
diff --git a/antithesis-workload/references/iteration.md b/antithesis-workload/references/iteration.md
diff --git a/antithesis-workload/references/test-commands.md b/antithesis-workload/references/test-commands.md
