# Monotonic settlement for shared durable operation records

Locked reservation plus binding-gated monotonic merge for shared durable operation records, with explicit atomic claim, stale-work suppression, and caller-scoped conflict semantics.

Exact reference: {"kind":"skill_version","skill_id":"skl_tLh4bGUyRxd2Vx-upIHeMw","version_id":"skv_c-M1uRLQ8wyFN97j6UyhBA"}

Applicability: []

# Monotonic settlement for shared durable operation records

## When to use

Multiple client retries share one durable operation record keyed by an idempotency key. Attempts can finish in either order. Naive last-write-wins can overwrite completed with unknown. Monotonic merge alone is insufficient when a late success carries the correct operation id but a different request fingerprint or authorization binding generation.

## Core rule

Separate canonical operation outcome from per-attempt observations. Settlement is **locked monotonic merge**: match the reservation lock first, then apply rank-based merge.

## Locked reservation (claim phase)

On first claim, atomically record an immutable reservation lock using compare-and-set (set lock only if unset):

- operation_id — idempotency key scoped to tenant or actor
- request_fingerprint — hash of effect-defining fields
- authorization_binding — principal, tenant, scopes, and binding generation

Claim rules:

- Same operation id plus matching fingerprint and binding: join in-flight or settled operation.
- Same operation id plus mismatch: conflict at claim; do not grant execution permission.
- Lock is immutable for the record lifetime.

## Atomic claim and execute

Claim acquisition and execution permission must be one atomic step (or equivalent lease or worker token tied to the lock). Settlement must not accept observations from workers that never held a valid claim. Mismatched fingerprint or binding cannot both execute and canonicalize.

Settlement can reject mismatched late success even if external side effects occurred; duplicate or wrong-intent effects require an idempotent effect layer separately from canonical replay.

## Binding revocation at settlement

At settlement time, re-check that the worker binding generation is still valid for the reserved lock, or that the client has not superseded it. A worker holding an old generation must not settle to completed after the client re-authenticates to a new generation, even if it matches the originally locked generation.

## Status lattice

Within the same lock: pending/running less than unknown less than conflict less than failed less than completed.

Upgrade to completed only when fingerprint and binding match the reservation and settlement binding check passes. Mismatched completed observations: reject or set conflict; never upgrade canonical.

## Conflict semantics (caller-scoped)

Conflict is mid-rank: matching-lock success may still upgrade conflict to completed or failed. Callers with matching lock should keep polling through transient conflict. Callers with mismatched fingerprint or binding must not replay any result on conflict.

## Effect determinism assumption

Matching lock plus monotonic merge assumes deterministic effects or equivalent results across matching-lock successes. State this assumption or add result-equivalence checks.

## Completion orders

- Order A (matching lock): success then timeout — completed preserved.
- Order B (matching lock): timeout then success — upgrades to completed.
- Order C (mismatch): late success with wrong fingerprint or binding — must not reach completed.

## Client contract

Retry with same operation id, fingerprint, and current valid binding generation. New intent requires new operation id. After re-auth, treat prior in-flight attempts as stale. On conflict with mismatched lock: do not replay. On conflict with matching lock: continue polling until terminal completed or failed.

## What to verify in tests

- CAS first-claim races.
- Atomic claim blocks mismatched settlement.
- Binding bump blocks stale-generation settlement.
- Matching-lock client polls through transient conflict.
- Mismatched late success never canonicalizes.


## Supporting basis and limitations

Subagent review flagged stale in-flight completion after re-auth, TOCTOU between claim and execute, first-claim race without CAS, ambiguous conflict handling, and missing determinism assumption.

## Change and rationale

Add atomic claim-and-execute, CAS lock creation, binding revocation at settlement, transient conflict polling guidance, and effect determinism assumption from independent review.

Independent review found the core two-phase settlement sound but identified holes in stale binding settlement, claim-execute atomicity, first-claim races, and conflict caller-scoping.