docs: state the wire-marker deploy ordering and the options-type rename

- The v8 upgrade guide now has a rolling-upgrade warning for the typed-error
  wire marker. A data-less contract error emitted by a 7.x worker carries no
  marker, so an 8.0 reader degrades it to a generic failure — silently, unless
  `onRehydrationMiss` is registered. Documents workers-before-callers ordering,
  the hook, and that schema-bearing errors are unaffected. Added to the
  checklist.
- `ActivityDefaultOptions` -> `ContractActivityOptions` in the rename table,
  the checklist, the contract-surface reference, and the changeset.

Author: btravers

.changeset/v8-audit-remediation.md

@@ -16,7 +16,7 @@ v8 audit remediation — a second full-surface pass hardening robustness, the un
 **`@temporal-contract/contract`:**
 
 - Type-helper renames to the family-standard `Infer*` prefix: `SignalNamesOf`/`QueryNamesOf`/`UpdateNamesOf`/`DeclaredErrorsOf` → `InferSignalNames`/`InferQueryNames`/`InferUpdateNames`/`InferDeclaredErrors`.
-- `defineActivity`'s `defaultOptions` key is renamed `activityOptions` (merge precedence unchanged).
+- `defineActivity`'s `defaultOptions` key is renamed `activityOptions` (merge precedence unchanged), and its type `ActivityDefaultOptions` → `ContractActivityOptions` — the new name keeps the contract-level, portable subset distinct from Temporal's own `ActivityOptions`, which is what the worker-side `activityOptionsByName` overrides take.
 - Duration strings are validated against the `ms` grammar at `defineContract` time — `"5 minutos"`, `""`, and negative durations now fail at definition, naming the offending path, instead of at the worker.
 - Temporal-reserved names are rejected at `defineContract`: the `__temporal_` prefix and the exact `__stack_trace` / `__enhanced_stack_trace` query names.
 - Activity-only contracts are allowed — `workflows` may be `{}` when at least one global activity is declared (dedicated activity-pool task queues).

docs/how-to/upgrade-to-v8.md

@@ -642,6 +642,7 @@ integration, and family consistency. These land in the same major.
 | `SignalNamesOf` / `QueryNamesOf` / `UpdateNamesOf`      | `InferSignalNames` / `InferQueryNames` / `InferUpdateNames` |
 | `DeclaredErrorsOf`                                      | `InferDeclaredErrors`                                       |
 | `defineActivity({ defaultOptions })`                    | `defineActivity({ activityOptions })`                       |
+| `ActivityDefaultOptions` (type)                         | `ContractActivityOptions`                                   |
 | `context.defineSignal` / `defineQuery` / `defineUpdate` | `context.handleSignal` / `handleQuery` / `handleUpdate`     |
 | `@temporal-contract/contract/result-async`              | removed — internals live at `.../internal` (private)        |
 
@@ -697,6 +698,37 @@ it. Re-raise with the new `rethrowCancellation(error)` from
 `@temporal-contract/worker/workflow`. See
 [Handle cancellation](/how-to/handle-cancellation).
 
+### Typed errors carry a wire marker — mind the deploy order
+
+A contract error now crosses the wire with a provenance marker in
+`ApplicationFailure.details[1]` (`{ $tc: 1 }`). For an error that declares a
+`data` schema, validating `details[0]` is still the gate. For a **data-less**
+error the marker is **required** — that closes a false positive where any
+unrelated `ApplicationFailure` whose `type` happened to equal a declared
+data-less error name was surfaced as the typed domain error.
+
+::: warning Rolling upgrades
+The marker is written by 8.0 workers only. During a rolling deploy, a
+**data-less** contract error emitted by a still-7.x worker carries no marker,
+so an 8.0 workflow or client will not rehydrate it — it degrades to the
+generic failure classification. Nothing throws and nothing is logged by
+default, so a `match` arm keyed on the typed error silently stops matching for
+the duration of the window.
+
+Order the deploy **workers first, then clients/callers**, and drain in-flight
+executions before cutting callers over. To make the window observable, register
+the diagnostic hook — it fires on every degrade-to-generic:
+
+```typescript
+import { onRehydrationMiss } from "@temporal-contract/contract/errors";
+
+onRehydrationMiss((miss) => logger.warn({ miss }, "contract error degraded to generic"));
+```
+
+Errors that declare a `data` schema are unaffected: they rehydrate on schema
+validation, marker or not.
+:::
+
 ### Worker: safer declarations
 
 - A shared activity referenced from several scopes must be the **same function
@@ -772,7 +804,8 @@ contract-error wire round-trip) so a test fails exactly where production does.
 - [ ] No schema relies on its transform running on the send side (each
       boundary now parses once, on receive)
 - [ ] `SignalNamesOf` / `QueryNamesOf` / `UpdateNamesOf` / `DeclaredErrorsOf`
-      → the `Infer*` prefix; `defineActivity` `defaultOptions` → `activityOptions`
+      → the `Infer*` prefix; `defineActivity` `defaultOptions` → `activityOptions`;
+      the `ActivityDefaultOptions` type → `ContractActivityOptions`
 - [ ] `context.defineSignal` / `defineQuery` / `defineUpdate` →
       `handleSignal` / `handleQuery` / `handleUpdate`
 - [ ] Every `qualifyFailure(...)` passes `{ expected }` (or `{ expected: "any" }`
@@ -786,6 +819,9 @@ contract-error wire round-trip) so a test fails exactly where production does.
 - [ ] `createContractTest({ contract, ... })` and `runActivity(def, { ... })`
       use the option bag; `testcontainers` installed only where `createContractTest` runs
 - [ ] Imports of `@temporal-contract/contract/result-async` removed
+- [ ] Rolling deploy ordered **workers before callers**, and `onRehydrationMiss`
+      registered — a data-less contract error from a 7.x worker carries no wire
+      marker and degrades to a generic failure until the workers are cut over
 - [ ] `@temporalio/*` resolve to `^1.16.0`; no CJS `require` of these packages
 - [ ] `pnpm typecheck` clean
 

docs/reference/contract-surface.md

@@ -75,11 +75,13 @@ relaxes when the contract exists purely to serve activities.
 | `input`           | `AnySchema`                       | yes      |
 | `output`          | `AnySchema`                       | yes      |
 | `errors`          | `Record<string, ErrorDefinition>` | no       |
-| `activityOptions` | `ActivityDefaultOptions`          | no       |
+| `activityOptions` | `ContractActivityOptions`         | no       |
 
 ::: info Renamed in 8.0
 The contract-level activity-options field is `activityOptions` (it was
-`defaultOptions` before 8.0). Its type is still `ActivityDefaultOptions`.
+`defaultOptions` before 8.0), and its type is `ContractActivityOptions` (it
+was `ActivityDefaultOptions`). The type name is now distinct from Temporal's
+own `ActivityOptions`, which is what the worker-side overrides take.
 :::
 
 ### `defineSignal(definition?)`
@@ -159,12 +161,12 @@ type ErrorDefinition = {
 | `message`      | Default message. Overridable per instance                                                     |
 | `nonRetryable` | `true` stops Temporal retrying. Default `false`                                               |
 
-### `ActivityDefaultOptions`
+### `ContractActivityOptions`
 
 A strict object — unknown keys are rejected at `defineContract` time.
 
 ```typescript
-type ActivityDefaultOptions = {
+type ContractActivityOptions = {
   startToCloseTimeout?: DurationValue;
   scheduleToCloseTimeout?: DurationValue;
   scheduleToStartTimeout?: DurationValue;