@openwop/spec-artifacts 2.42.6 → 2.42.8

package/spec/v2/core/form-content-packs.md

@@ -1,15 +1,15 @@
 # Form Content Packs
 
-> **Status: Stable · RFC 0177, RFC 0137.**
+> **Status: Stable.**
 > **Normative home:** `forms`.
 
 ## Why this exists
 
-A form-content pack ships declarative form templates a host renders in its own chrome. The manifest is `schemas/v2/form-content-pack-manifest.schema.json`; installation and signing follow packs.md.
+A form-content pack ships declarative form templates a host renders in its own chrome. The manifest is `schemas/v2/form-content-pack-manifest.schema.json`; installation and signing follow [packs.md](packs.md).
 
 ## Conditional visibility
 
-A field MAY carry `when: <EdgeCondition>`. The grammar is the `WorkflowEdge.condition` object `{ type, left, right }` of `schemas/v2/workflow-definition.schema.json`, with the operator set of workflow-chain-packs.md §"Edge conditions". A host MUST evaluate `when` with its edge-condition semantics and MUST NOT accept any other expression language for visibility.
+A field MAY carry `when: <EdgeCondition>`. The grammar is the `WorkflowEdge.condition` object `{ type, left, right }` of `schemas/v2/workflow-definition.schema.json`, with the operator set of [workflow-chain-packs.md §"Edge conditions"](workflow-chain-packs.md). A host MUST evaluate `when` with its edge-condition semantics and MUST NOT accept any other expression language for visibility.
 
 ```jsonc
 { "id": "region", "type": "select", "label": "Region",
@@ -18,19 +18,15 @@ A field MAY carry `when: <EdgeCondition>`. The grammar is the `WorkflowEdge.cond
 
 ## Instantiation
 
-A form instantiated from a pack advertised through `forms.contentPacks` MUST be
-created through the same path a hand-authored form uses, and MUST remain
-editable afterwards: the pack is a starting point, not a managed object. A host
-MUST degrade an unrecognized field type to plain text rather than failing the
-instantiation, and MUST NOT execute anything carried by the pack. A pack-authored
-string, and any value collected through an instantiated template, is untrusted
-input: when one is interpolated into a prompt, the composed envelope MUST carry
-`meta.contentTrust: "untrusted"`, so a downstream reader can tell authored text
-from pack-supplied text.
+A form instantiated from a pack advertised through `forms.contentPacks` MUST be created through the same path a hand-authored form uses, and MUST remain editable afterwards: the pack is a starting point, not a managed object.
+
+- A host MUST degrade an unrecognized field type to plain text rather than failing the instantiation.
+- A host MUST NOT execute anything carried by the pack.
+- A pack-authored string, and any value collected through an instantiated template, is untrusted input. When one is interpolated into a prompt, the composed envelope MUST carry `meta.contentTrust: "untrusted"`, so a downstream reader can tell authored text from pack-supplied text.
 
 ## Localized strings
 
-`label`, `title`, and `description` are localized strings. A host MUST select the rendered language by the locale-selection and fallback rules of i18n.md, and MUST treat every rendered string as untrusted: escaped for the target surface, never interpreted as markup, script, or a template directive.
+`label`, `title`, and `description` are localized strings. A host MUST select the rendered language by the locale-selection and fallback rules of [i18n.md](i18n.md), and MUST treat every rendered string as untrusted: escaped for the target surface, never interpreted as markup, script, or a template directive.
 
 ## Validation
 
@@ -43,3 +39,5 @@ from pack-supplied text.
 | `pattern` | `text`, `longtext` | a host MUST reject a non-matching value |
 
 The five spec-reserved `format` values are the core set. A host that recognizes a format SHOULD apply it; one that does not MUST ignore it and accept plain text. A host MUST ignore `format` on any type other than `text` or `longtext`.
+
+*Sources: RFC 0137, RFC 0177.*

package/spec/v2/core/headers.md

@@ -1,41 +1,50 @@
 # Headers
 
-> **Status: Stable · RFC 0171 §C.1, RFC 0172 §A.3–§A.4.** GENERATED by `scripts/derive-v2-api.py` from `api/v2/openapi.yaml`; do not edit.
+> **Status: Stable.** Generated from `api/v2/openapi.yaml` by `scripts/derive-v2-api.py`; do not edit.
 
 ## Why this exists
 
-RFC 0171 §C.1: every non-standard header is `OpenWOP-<Name>` and every header is declared in OpenAPI, so this table — generated from the same declaration — enumerates all of them. A header that is not in this table is not part of the protocol. Standard headers keep their standard names (`Idempotency-Key`, `ETag`, `If-None-Match`, `Last-Event-ID`, `Retry-After`, `Authorization`).
+Every non-standard header is named `OpenWOP-<Name>`, and every header is declared in OpenAPI. These tables are generated from that declaration, so they list all of them: a header not listed here is not part of the protocol.
+
+Standard headers keep their standard names: `Idempotency-Key`, `ETag`, `If-None-Match`, `Last-Event-ID`, `Retry-After`, `Authorization`.
 
 ## Request headers
 
 | Header | Operations | Meaning |
 | --- | --- | --- |
-| `Accept-Language` | 1 | BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT 400. |
-| `Idempotency-Key` | 15 | Per-mutation idempotency token (see `idempotency.md` Layer 1). |
-| `If-None-Match` | 2 | RFC 0165 §C.2; runs.md §Snapshot. Standard conditional request against any resource that carries an `ETag` — the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot): a matching value MUST yield `304 Not Modified` with no body, and the 304 carries `OpenWOP-Version` like every response (versioning.md §1.4). |
+| `Accept-Language` | 1 | BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT produce a 400. |
+| `Idempotency-Key` | 15 | Per-mutation idempotency token (`idempotency.md` Layer 1). The server caches `(tenantId, endpoint, key)` → response for ≥24h. A duplicate request returns the cached response with `OpenWOP-Idempotent-Replay: true`. |
+| `If-None-Match` | 2 | Conditional request on the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot). A value matching the `ETag` the host sent MUST yield `304 Not Modified` with no body. The 304 carries `OpenWOP-Version` like every response (versioning.md §1.4). |
 | `Last-Event-ID` | 1 | Resume from sequence after this ID. |
-| `OpenWOP-Dedup` | 1 | When set, server cross-host claim system rejects duplicate `(tenantId, scopeId)` pairs with `409 Conflict`. |
-| `OpenWOP-Force-Engine-Version` | 1 | **Test-keys-only.** When set, the server emits events for this run AS IF it |
-| `OpenWOP-Version` | 55 | RFC 0172 §A.3 — selects a listed major.minor; absent ⇒ the host's `preferredVersion`; unlisted ⇒ 406 protocol_version_unsupported. |
+| `OpenWOP-Client-Version` | 55 | The protocol version the client implements (versioning.md §1.5). Compared with `minClientVersion` on major.minor. A malformed value is treated as absent and MUST NOT produce a 400. Never selects a contract. |
+| `OpenWOP-Dedup` | 1 | When set, the host's cross-host claim system rejects a duplicate `(tenantId, scopeId)` pair with `409 Conflict`. |
+| `OpenWOP-Force-Engine-Version` | 1 | Test keys only. The server emits this run's events as if it ran the given engine version, which must be within `Capabilities.testing.forceEngineVersionRange`. Servers MUST reject it on production API keys with `403 force_engine_version_forbidden`. |
+| `OpenWOP-Version` | 55 | Selects one of the host's listed major.minor versions. Absent, `/.well-known/openwop` uses `preferredVersion` and every other unversioned path is v2; an unlisted value is 406 protocol_version_unsupported. |
 
 ## Response headers
 
 | Header | Operations | Meaning |
 | --- | --- | --- |
-| `Cache-Control` | 2 |  |
-| `Content-Encoding` | 1 | RFC 0115. Present only when the host negotiated compression |
+| `Cache-Control` | 2 | Standard HTTP caching directive (RFC 9111), set per operation: public content-page delivery, and prompt templates (immutable semantics when the version was pinned); see each operation. |
+| `Content-Encoding` | 1 | Present only when the host negotiated compression from `Accept-Encoding`; pairs with `Vary: Accept-Encoding`. The decoded body is byte-identical to the identity body. |
 | `Content-Language` | 1 | The BCP-47 locale actually used (equals the response `locale`). |
 | `ETag` | 3 | Standard HTTP validator (RFC 9110 §8.8.3). The obligation is per operation: MUST on the discovery document (capabilities.md §1), SHOULD on the run snapshot (runs.md §Snapshot), a content hash on a prompt template (getPromptTemplate); see each operation. |
 | `Location` | 1 | Canonical URI of the new template. |
 | `OpenWOP-Idempotent-Replay` | 1 | Set when the response was served from the idempotency cache. |
-| `OpenWOP-Version` | 55 | RFC 0172 §A.4 — the contract that produced this response; MUST equal the one used. |
+| `OpenWOP-Version` | 55 | The contract that produced this response. It MUST equal the one used. |
 | `Retry-After` | 1 | Seconds until the active claim is stale-eligible. |
-| `WWW-Authenticate` | 48 | RFC 0200 §B — `Bearer` challenge; `resource_metadata` and `error="invalid_token"` on a host with an oauth2/oidc lane. Never on a non-disclosure 404. |
+| `WWW-Authenticate` | 48 | A `Bearer` challenge. On a host with an oauth2 or oidc lane it carries `resource_metadata` and `error="invalid_token"`. Never sent on a non-disclosure 404. |
 
 ## Webhook delivery headers
 
-Declared in `webhooks.md`, not in OpenAPI (the host is the client): `OpenWOP-Webhook-Id`, `OpenWOP-Event-Type`, `OpenWOP-Timestamp`, `OpenWOP-Signature`, `OpenWOP-Signature-Algorithm` (RFC 0165 §C.1). The `X-openwop-*` family is emitted beside them through the overlap and removed at v1 end-of-support (`spec/v1/deprecations.json` `webhook-x-header-family`). On a subscription that opted into Standard Webhooks (webhooks.md), that standard's `webhook-id`, `webhook-timestamp` and `webhook-signature`, which keep their standard names (RFC 0201 §F).
+Declared in `webhooks.md`, not in OpenAPI, because the host is the client:
+
+- `OpenWOP-Webhook-Id`, `OpenWOP-Event-Type`, `OpenWOP-Timestamp`, `OpenWOP-Signature`, `OpenWOP-Signature-Algorithm`.
+- On a subscription that opted into Standard Webhooks (webhooks.md): that standard's `webhook-id`, `webhook-timestamp` and `webhook-signature`, under their standard names.
+- During the v1 overlap only: the `X-openwop-*` family, emitted beside them and removed at v1 end-of-support.
 
 ## Removed in v2
 
-`Capabilities-Etag` (the standard `ETag`/`If-None-Match` pair applies to the discovery document), `X-Dedup`, `X-Force-Engine-Version`, `X-Pack-Sha256`, `X-Pack-Signing-Method` (renamed under the one scheme), `X-openwop-*` (webhooks), `openwop-Webhook-Signature` (SDK-only). Each has a `spec/v1/deprecations.json` row with a removal trigger.
+These header names are not part of v2: `Capabilities-Etag` (use the standard `ETag`/`If-None-Match` pair), `X-Dedup`, `X-Force-Engine-Version`, `X-Pack-Sha256`, `X-Pack-Signing-Method`, `X-openwop-*` (webhooks), `openwop-Webhook-Signature`.
+
+*Sources: RFC 0165, RFC 0171, RFC 0172, RFC 0201.*

package/spec/v2/core/host-services.md

@@ -1,19 +1,27 @@
 # Host services
 
-> **Status: Stable · v2.0 · RFC 0144.** Normative contract for the advertised `host.*` service surfaces a node pack invokes through `ctx`.
+> **Status: Stable.**
 > **Normative home:** `aiEnvelope`, `promptLibrary`, `agentRuntime`, `mcp`.
 
 ## Why this exists
 
-`spec/v1/host-capabilities.md` describes these three surfaces but states no RFC 2119 obligation; the contract a host takes on by advertising them is written here.
+A node pack invokes advertised `host.*` services through `ctx`. This document states the contract a host takes on by advertising them.
 
 ## `aiEnvelope`
 
-A host advertising `aiEnvelope` MUST expose `ctx.aiEnvelope.generate` to pack code, and MUST refuse a node whose `typeId` requires the family when it does not advertise it. It MUST expose `ctx.aiEnvelope.await` when, and only when, it advertises `aiEnvelope.await`.
+A host advertising `aiEnvelope`:
+
+- MUST expose `ctx.aiEnvelope.generate` to pack code;
+- MUST refuse a node whose `typeId` requires the family when it does not advertise it;
+- MUST expose `ctx.aiEnvelope.await` when, and only when, it advertises `aiEnvelope.await`.
 
 ## `promptLibrary`
 
-A host advertising `promptLibrary` MUST expose `ctx.promptLibrary.get`, MUST return a pinned version verbatim so that a replayed run resolves the same template, and MUST fail the calling node rather than substitute an unpinned one.
+A host advertising `promptLibrary`:
+
+- MUST expose `ctx.promptLibrary.get`;
+- MUST return a pinned version verbatim, so that a replayed run resolves the same template;
+- MUST fail the calling node rather than substitute an unpinned one.
 
 ## `agentRuntime`
 
@@ -21,4 +29,13 @@ A host advertising `agentRuntime` MUST expose `spawn`, `delegate`, `consensus` a
 
 ## `mcp`
 
-A host advertising `mcp.client` MUST expose to pack code `ctx.mcp.callTool`, `listTools`, `readResource` and `serverHealth`, each against a host-configured `serverId` at the revision `mcp` negotiates. Each rejects only for an unknown `serverId` (`not_found`), an MCP error response (carried unaltered), or a transport failure. `callTool` MUST resolve to the server's `CallToolResult` unaltered (`content[]`, `structuredContent`, `isError`, `_meta`), including when `isError` is true; the host handles an `InputRequiredResult` itself and never returns one. `listTools` MUST resolve to one `ListToolsResult` page unaltered, `outputSchema`, `annotations`, `nextCursor`, `ttlMs` and `cacheScope` included, and MUST forward a pack's `cursor`; `readResource` resolves to the `ReadResourceResult` unaltered. `serverHealth` MUST report `reachable`, `unreachable` or `incompatible` from a `server/discover` probe no older than its `ttlMs`, with the `DiscoverResult` when one was received; it MUST NOT report a connection or session state, which MCP 2026-07-28 does not have.
+A host advertising `mcp.client` MUST expose to pack code `ctx.mcp.callTool`, `listTools`, `readResource` and `serverHealth`, each against a host-configured `serverId` at the revision `mcp` negotiates.
+
+Each rejects only for an unknown `serverId` (`not_found`), an MCP error response (carried unaltered), or a transport failure.
+
+- `callTool` MUST resolve to the server's `CallToolResult` unaltered (`content[]`, `structuredContent`, `isError`, `_meta`), including when `isError` is true. The host handles an `InputRequiredResult` itself and never returns one.
+- `listTools` MUST resolve to one `ListToolsResult` page unaltered, `outputSchema`, `annotations`, `nextCursor`, `ttlMs` and `cacheScope` included, and MUST forward a pack's `cursor`.
+- `readResource` resolves to the `ReadResourceResult` unaltered.
+- `serverHealth` MUST report `reachable`, `unreachable` or `incompatible` from a `server/discover` probe no older than its `ttlMs`, with the `DiscoverResult` when one was received. It MUST NOT report a connection or session state, which MCP 2026-07-28 does not have.
+
+*Sources: RFC 0144.*

package/spec/v2/core/i18n.md

@@ -0,0 +1,64 @@
+# Internationalization
+
+> **Status: Stable.**
+> **Normative home:** `i18n`.
+
+## Why this exists
+
+A host renders some text for humans: interrupt prompts, error messages, extension UI strings. This document states how a client asks for a locale and how a host answers. Machine-readable identifiers stay ASCII, dates and times stay ISO 8601, and number, currency and text-direction formatting are out of scope.
+
+## Language tags
+
+Every locale identifier — `Accept-Language`, `Content-Language` and every `locale` field — is a [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) tag.
+
+- Tags compare case-insensitively (RFC 5646 §2.1.1, RFC 4647 §2).
+- A host SHOULD advertise and emit tags in the case RFC 5646 §2.1.1 recommends: lowercase language, titlecase script, uppercase region (`zh-Hant-TW`, `es-419`).
+
+## `Accept-Language`
+
+A client MAY send `Accept-Language` ([RFC 9110 §12.5.4](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.4)) on any request. A host MAY honor it to localize human-facing text in the response.
+
+A host:
+
+- MUST parse the header without failing the request. A malformed value MUST NOT cause `400`; the host uses its default locale and proceeds.
+- MUST NOT reject a request because it does not support the requested locale.
+- MUST honor q-values: the highest-q locale it supports wins, and ties go to request order.
+- MUST NOT infer a locale from the request body to override the header, which is authoritative.
+- SHOULD set `Content-Language` to the canonical tag of the locale used when it localized the response. When it localized nothing, it SHOULD omit `Content-Language` or set it to its default locale.
+- MAY cache localized text. When localization is expensive, caching by `(localeTag, sourceText)` is RECOMMENDED.
+- MAY return default-locale text at once and emit `node.completed` when the localized version is ready. This is discouraged for an interrupt prompt, which a human needs localized now.
+
+## Fallback
+
+When a host cannot localize to the requested locale, it:
+
+1. walks the list in q-value order and uses the first locale it supports;
+2. otherwise tries the language family: asked for `ja-JP` and holding only `ja`, it uses `ja` and sets `Content-Language: ja`;
+3. otherwise uses its default locale, which it SHOULD advertise as `i18n.defaultLocale`;
+4. sets `Content-Language` to the locale it actually used, never another.
+
+## Error envelopes
+
+A host MAY localize an error `message`, and MAY then add `details.locale`.
+
+- The `error` code MUST be the same registered identifier in every locale ([errors.md](errors.md)); it is never translated.
+- `details` keys are schema field names and are not localized.
+- A human-facing `details` value MAY be localized, and SHOULD carry a `locale` sibling on the same object.
+
+## The `i18n` record
+
+A host that negotiates locale SHOULD advertise `i18n`. A host advertising it honors `Accept-Language` on every protected route; a host that omits it serves one locale.
+
+- **`defaultLocale`** — the locale returned when no `Accept-Language` entry matches `supportedLocales`; `"en"` when omitted.
+- **`supportedLocales`** — the locales the host can return for human-facing text. It MUST contain `defaultLocale`, and its order carries no meaning.
+- A host that translates by machine SHOULD list only the locales it has validated end to end.
+
+## Replay and fork
+
+Locale is chosen at request time. `Content-Language` is request-scoped and not recorded in the event log, so a replay re-projects the recorded text and does not re-render it. A fork localizes by its own request's `Accept-Language`, not the parent run's.
+
+## Clients
+
+A client that wants localized content MUST check discovery for `i18n` before sending `Accept-Language`. A host that does not advertise it ignores the header and returns its default locale.
+
+*Sources: RFC 0206.*

package/spec/v2/core/idempotency.md

@@ -1,59 +1,71 @@
 # Idempotency
 
-> **Status: Stable · RFC 0170 §D.3, RFC 0171 §B.2, RFC 0173 §B.**
+> **Status: Stable.**
 > **Normative home:** `idempotency`.
 
 ## Why this exists
 
-A retried request MUST NOT create a second run, and a retried node MUST NOT issue a second external effect. A host MUST implement Layer 1 for every mutating endpoint; a host that advertises `idempotency` MUST implement Layer 2 for every node executor that performs an external side effect (security-defaults.md).
+A retried request MUST NOT create a second run, and a retried node MUST NOT issue a second external effect. A host MUST implement Layer 1 for every mutating endpoint; a host that advertises `idempotency` MUST implement Layer 2 for every node executor that performs an external side effect ([security-defaults.md](security-defaults.md)).
 
 ## Layer 1: `Idempotency-Key`
 
-The header keeps its standard name (RFC 0171 §C.1) and applies to every mutating operation in `api/v2/openapi.yaml`; `GET` operations MUST NOT honor it.
-
-| Rule | Requirement |
-| --- | --- |
-| Grammar | The value MUST match `^[A-Za-z0-9._~-]{22,128}$` and MUST carry at least 128 bits of entropy (a UUIDv4 in canonical or base64url form satisfies it). A host MUST reject a value outside the grammar with `400 idempotency_key_invalid`. |
-| Record key | A record MUST be keyed by `(authenticatedTenantId, canonicalEndpointId, callerIdempotencyKey)`; the tenant MUST come from the credential, never the body. |
-| Final outcomes | A host MUST cache `2xx` and non-retryable `4xx` responses (status, headers, body) and MUST return the cached response to a same-key duplicate. |
-| Retryable outcomes | `429` and `5xx` MUST NOT be replayed from cache; a same-key retry MUST re-execute, and a later final outcome replaces the record. |
-| Not cached | `400 idempotency_key_invalid`, `400 validation_error`, `401` and `403` MUST NOT be cached. |
-| Digest mismatch | A different request digest under the same record key MUST fail with `409 idempotency_key_mismatch` and MUST NOT return the cached body. This is the only mismatch code. |
-| Concurrency | Of two concurrent same-key requests a host MUST process exactly one to completion and MUST NOT process both. The other MAY wait, bounded by the host's request timeout, and receive the winner's response only if it is a final outcome (one this record caches), marked `OpenWOP-Idempotent-Replay: true`. Otherwise the host MUST answer `409 idempotency_in_flight` with no retry timing in `details`, and SHOULD set `Retry-After`. The code's registry `retriable: false` means not retryable without waiting (RFC 0213 §B). |
-| Replay marker | A response served from cache MUST carry `OpenWOP-Idempotent-Replay: true`. |
-| Retention | A record MUST be retained for at least 24 hours. |
-| Keyspace | Host-minted identifiers MUST NOT share the caller idempotency store. Logs and spans MUST NOT expose keys. |
+The header keeps its standard name and applies to every mutating operation in `api/v2/openapi.yaml`; `GET` operations MUST NOT honor it.
+
+### Key and record
+
+- **Grammar.** The value MUST match `^[A-Za-z0-9._~-]{22,128}$` and MUST carry at least 128 bits of entropy (a UUIDv4 in canonical or base64url form satisfies it). A host MUST reject a value outside the grammar with `400 idempotency_key_invalid`.
+- **Record key.** A record MUST be keyed by `(authenticatedTenantId, canonicalEndpointId, callerIdempotencyKey)`; the tenant MUST come from the credential, never the body.
+- **Retention.** A record MUST be retained for at least 24 hours.
+- **Keyspace.** Host-minted identifiers MUST NOT share the caller idempotency store. Logs and spans MUST NOT expose keys.
+
+### Outcomes
+
+- **Final.** A host MUST cache `2xx` and non-retryable `4xx` responses (status, headers, body) and MUST return the cached response to a same-key duplicate.
+- **Retryable.** `429` and `5xx` MUST NOT be replayed from cache; a same-key retry MUST re-execute, and a later final outcome replaces the record.
+- **Not cached.** `400 idempotency_key_invalid`, `400 validation_error`, `401` and `403` MUST NOT be cached.
+- **Digest mismatch.** A different request digest under the same record key MUST fail with `409 idempotency_key_mismatch` and MUST NOT return the cached body. This is the only mismatch code.
+- **Replay marker.** A response served from cache MUST carry `OpenWOP-Idempotent-Replay: true`.
+
+### Concurrency
+
+Of two concurrent same-key requests a host MUST process exactly one to completion and MUST NOT process both.
+
+- The other MAY wait, bounded by the host's request timeout, and receive the winner's response only if it is a final outcome (one this record caches), marked `OpenWOP-Idempotent-Replay: true`.
+- Otherwise the host MUST answer `409 idempotency_in_flight` with no retry timing in `details`, and SHOULD set `Retry-After`.
+
+The code's registry `retriable: false` means not retryable without waiting.
 
 ## Layer 2: effect identity
 
-Layer 2 is bound by advertising `idempotency` (security-defaults.md). Its unit is the **effect**, identified once and stable across every transport or provider retry.
+Layer 2 is bound by advertising `idempotency` ([security-defaults.md](security-defaults.md)). Its unit is the **effect**, identified once and stable across every transport or provider retry.
 
-| Rule | Requirement |
-| --- | --- |
-| Keying | An effect MUST be keyed on its business identity (`keying: business-identity`): derived from the business operation, stable across every entry point, containing no `runId`, `nodeId` or ordinal. The activity recipe (`keying: activity-recipe`: tenant, run, node, ordinal, `providerKey`) is the fallback for a provider with no business key. |
-| Attempts | The retry counter MUST NOT participate in the identity. Two distinct logical invocations MUST receive different identities. |
-| Claim | The persist that guards the effect MUST be an atomic claim (compare-and-set or insert-if-absent) that at most one executor can win, so at most one concurrent duplicate performs the effect. |
-| Provider key | When the provider accepts an idempotency key, the host MUST inject the effect identity (or a documented deterministic derivative), stable across retries. A host that cannot use the provider's convention MUST still persist the outcome. |
-| Streaming | A streamed body MUST NOT be cached in the ledger; the host SHOULD record the request and its final outcome. |
-| Retention | An effect record MUST be retained for at least 14 days. |
+- **Keying.** An effect MUST be keyed on its business identity (`keying: business-identity`): derived from the business operation, stable across every entry point, containing no `runId`, `nodeId` or ordinal. The activity recipe (`keying: activity-recipe`: tenant, run, node, ordinal, `providerKey`) is the fallback for a provider with no business key.
+- **Attempts.** The retry counter MUST NOT participate in the identity. Two distinct logical invocations MUST receive different identities.
+- **Claim.** The persist that guards the effect MUST be an atomic claim (compare-and-set or insert-if-absent) that at most one executor can win, so at most one concurrent duplicate performs the effect.
+- **Provider key.** When the provider accepts an idempotency key, the host MUST inject the effect identity (or a documented deterministic derivative), stable across retries. A host that cannot use the provider's convention MUST still persist the outcome.
+- **Streaming.** A streamed body MUST NOT be cached in the ledger; the host SHOULD record the request and its final outcome.
+- **Retention.** An effect record MUST be retained for at least 14 days.
 
 ### Witness: `GET /runs/{runId}/effects`
 
-A host that advertises `idempotency` MUST serve `schemas/v2/effect-ledger-projection.schema.json` at `GET /runs/{runId}/effects` (`getRunEffects`): `{ runId, effects[] }`, each record carrying `effectId` (tenant-bound, `schemas/v2/ids.schema.json`), `nodeId`, `attempt`, `keying`, `state` (`claimed` | `completed` | `released` | `escaped`), `at`, optional `invocationId` and a redaction-safe `providerKey`. The projection MUST be content-free of provider payloads and credential material.
+A host that advertises `idempotency` MUST serve `schemas/v2/effect-ledger-projection.schema.json` at `GET /runs/{runId}/effects` (`getRunEffects`): `{ runId, effects[] }`. Each record carries:
+
+- `effectId` (tenant-bound, `schemas/v2/ids.schema.json`), `nodeId`, `attempt`, `keying`, `at`;
+- `state`: `claimed` | `completed` | `released` | `escaped`;
+- optional `invocationId` and a redaction-safe `providerKey`.
+
+The projection MUST be content-free of provider payloads and credential material.
 
 ## Composition
 
-Layer 1 deduplicates the caller's request; Layer 2 deduplicates the run's effects. A retried provider call inside a run MUST resolve to the same effect record. Effects under replay and fork are in replay.md; identifier grammars are in identity.md.
+Layer 1 deduplicates the caller's request; Layer 2 deduplicates the run's effects. A retried provider call inside a run MUST resolve to the same effect record. Effects under replay and fork are in [replay.md](replay.md); identifier grammars are in [identity.md](identity.md).
 
 ## Multi-region
 
-`multiRegion` and `crossRegion` are the two region facets of `idempotency`, and
-they claim different things. `crossRegion` names the host's deployment posture
-for this axis and MUST be held constant for the life of an advertisement.
-`multiRegion` is the behavioural claim: when a host advertises it, both layers
-above MUST hold across regions — an `Idempotency-Key` replayed into a second
-region MUST resolve to the first region's response rather than starting new
-work, and effect identity MUST collapse a duplicate effect wherever it is
-observed. A host that does not advertise `multiRegion` makes no cross-region
-promise, and a client MUST NOT infer one from `crossRegion` alone.
+`multiRegion` and `crossRegion` are the two region facets of `idempotency`, and they claim different things.
+
+- `crossRegion` names the host's deployment posture for this axis and MUST be held constant for the life of an advertisement.
+- `multiRegion` is the behavioural claim. When a host advertises it, both layers MUST hold across regions: an `Idempotency-Key` replayed into a second region MUST resolve to the first region's response rather than starting new work, and effect identity MUST collapse a duplicate effect wherever it is observed.
+- A host that does not advertise `multiRegion` makes no cross-region promise, and a client MUST NOT infer one from `crossRegion` alone.
 
+*Sources: RFC 0170, RFC 0171, RFC 0173, RFC 0213.*