ORA-2026-0135 - Hot-Claim Race Prevention

ORA-2026-0135 - Hot-Claim Race Prevention

Rule

Hot work claims must reserve the surface before they mutate or review it. There is one active owner per surface.

SURFACE_KEY names the artifact or reality slice being changed. It is not the ticket id. Ticket numbers prevent numeric collisions; surface keys prevent semantic collisions.

Why

The fleet can create multiple valid tickets within seconds for the same work. The feed reducer can prove each ticket is well-formed while still allowing two seats to mutate the same helper, page, branch, dataset, or review surface. That is a world-model failure: the queue says there are two independent objects, but the territory has one.

Hot-claim races showed this twice:

1. Multiple Camber tickets claimed the same Buildertrend push readiness surface. 2. Multiple Heartwood tickets claimed the same fixture proof/review surface.

The repair is to make the surface a first-class claim token at write time.

Protocol

1. Any active claim that mutates or reviews a bounded surface includes:

``text SURFACE_KEY: <lane>:<surface-family>:<specific-artifact> NO_OVERLAP_PROOF: <how this claim differs from nearby active work> ``

2. New tickets with a known surface use ticket-reserve --surface <key>.

3. Before claiming hot visible work, or any work posted in the last minute, run:

``text fleet-active-queue --surface-claim <key> ``

ALLOCATED means the surface is available. COLLIDE-WITH-<ITEM> means yield or amend the prior ticket instead of opening a second active claim.

4. feed-append rejects actionable AWAITING_CLAIM and IN_PROGRESS posts whose SURFACE_KEY matches another active claim.

5. Duplicates become PARKED, CANCELLED, or handoff amendments. They do not proceed in parallel against the same surface.

Surface Key Shape

Good keys are stable, narrow, and human-readable:

CAMBER:bt-push-readiness:known_production_bt_job_ids
HEARTWOOD:fixture-proof:job-40729171:auto-baseline
ORA:fleet-runtime-helper:feed-append
ORBIT:queue-helper:ticket-reserve

Avoid keys that are too broad (CAMBER:all-bt) or too local (my-branch). A good key lets another seat know whether their intended mutation would collide.

Exceptions

Broad parent objectives, purely narrative observations, read-only parked triggers, and auth blockers may omit SURFACE_KEY when no bounded surface is being claimed.

A same-item transition ignores its own current SURFACE_KEY, so the owning seat can move from AWAITING_CLAIM to IN_PROGRESS or DONE. Terminal states do not block future claims.

Disconfirming Observation

If duplicate hot claims still occur while carrying different surface keys, the key granularity is wrong. Tighten the surface family or specific artifact until the collision appears before mutation.

Enforcement

The fleet runtime enforces this through:

• fleet_queue_lib.py parsing, normalization, and collision checks.
• fleet-active-queue --surface-claim.
• ticket-reserve --surface.
• feed-append prewrite validation for duplicate active surface claims.
• Focused smokes for queue checks, allocator checks, and feed-append rejection.