Bounded Direct Publish with Idempotency and Verification

1. Problem: a timeout means “unknown,” not “definitely failed”

A create-style POST may reach a provider while the response is lost before the client receives it. Blindly repeating the request can create duplicates; refusing to act forever leaves the transaction ambiguous. This lesson produces Idempotent Publish Transaction & Verification Ledger v1.

2. Lesson boundary

PLN-023 owns the bounded direct-publish transaction from approved intent through final verification. PLN-022 shadow-mode promotion and PLN-024 account health/quota remain adjacent outcomes. The lab is synthetic and performs no external publish.

3. External FACT versus MAKNOW DESIGN

AIP-155 describes customer-provided request IDs as useful for de-duplication, safe retries, and idempotency guarantees when the API honors them. Google Cloud HTTP guidance treats GET/PUT/DELETE as idempotent and POST/PATCH as non-idempotent by method semantics alone. Ledger states and retry budgets are MAKNOW DESIGN.

4. Give the transaction an identity before retrying

publish_transaction_id and publish_intent_id bind one approved decision to a specific target_account and operation. A retry must not silently become a new intent or execute against another account.

5. Payload hash is part of request identity

payload_hash is not merely diagnostic. Reusing an idempotency key or request ID with a different payload must not be treated as the same transaction. Key reuse across payloads fails closed as DUPLICATE_BLOCKED or equivalent.

6. Record provider support explicitly

idempotency_support says whether the provider actually guarantees request-identity semantics. A client-defined header is not provider support. When the provider has no documented mechanism, name any application-side duplicate strategy separately.

7. Bound retry class and execution budget

attempt_no, retry_class, and execution_budget prevent infinite retry loops. A timeout with valid provider request identity may be retry-safe; a timeout without identity and without duplicate/read-back evidence remains AMBIGUOUS.

8. Response status is only one piece of evidence

200/201/202 describes a response, not proof that exactly the intended resource was created exactly once. provider_resource_id must bind back to the intended transaction and account.

9. Separate read-back verification from the response

verification_method and read_back_snapshot prove final state. Verification can re-read resource ID, target account, payload fingerprint, or critical fields. If read-back is unavailable, do not fabricate VERIFIED.

10. Duplicate detection must be traceable

duplicate_detection may use provider request identity, an application duplicate key, or a query/read endpoint. Its type and limitations belong in provenance. An application key never proves provider-side exactly-once semantics.

11. Freshness and provenance are transaction fields

Idempotency behavior, retention windows, and verification endpoints can change. Stale decisive evidence becomes STALE_EVIDENCE; missing provenance_ref becomes UNKNOWN or BLOCKED. Direct publish cannot replace evidence with optimism.

12. Baseline — timeout with a valid provider request ID

The provider officially supports request identity. Attempt one times out; the retry uses the same request ID and payload hash; the provider returns the same resource and read-back verifies account and payload. The final state is VERIFIED.

13. Dangerous shortcuts

Do not: treat timeout as definite failure; retry a POST with no identity; reuse one idempotency key for a new payload; accept 2xx as exactly-once proof; accept a resource from the wrong account; or keep retrying after the bounded budget is exhausted.

14. Transfer — provider with no official idempotency key

The transfer provider has no documented request-id mechanism but exposes a reliable read endpoint. The client derives an application duplicate key from intent+target+payload, performs read-before-retry, and sends a new request only when no matching resource is found and budget remains. The transaction may become VERIFIED, while provider_exactly_once=false remains explicit.

15. Lab, assessment, and freshness

Run python run_checks.py under lab/PLN-023-LAB1/learner/. Eight fixtures cover VERIFIED, AMBIGUOUS, DUPLICATE_BLOCKED, FAILED/UNVERIFIED, DEFERRED, STALE_EVIDENCE, UNKNOWN, and transfer. AIP-155 and Google Cloud HTTP guidance were rechecked on 2026-09-16.