{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="mb-4">
    <p class="text-uppercase text-primary fw-semibold small mb-2">Guide: understand the pieces</p>
    <h1 class="display-6 fw-semibold mb-2">Lease locks and ownership</h1>
    <p class="lead text-muted mb-0">
      Give one Pearing identity a time-limited claim on named work.
    </p>
  </div>

  <div class="row g-3 mb-4">
    <div class="col-12 col-lg-6"><div class="card h-100"><div class="card-body"><h2 class="h5">Use this when</h2><p class="mb-0">Different identities might perform the same non-idempotent step.</p></div></div></div>
    <div class="col-12 col-lg-6"><div class="card h-100"><div class="card-body"><h2 class="h5">Do not use this when</h2><p class="mb-0">Work is safe in parallel, the target already enforces uniqueness, or reviews must remain independent.</p></div></div></div>
  </div>

  <section class="mb-4" aria-labelledby="lock-pieces">
    <h2 class="h3" id="lock-pieces">Pieces involved</h2>
    <div class="d-flex flex-wrap gap-2">
      <span class="badge text-bg-secondary">Resolved user identity</span>
      <span class="badge text-bg-secondary">User, team, or repository scope</span>
      <span class="badge text-bg-secondary">Stable lock name</span>
      <span class="badge text-bg-secondary">Idempotent request UUID</span>
      <span class="badge text-bg-secondary">Ticket and lease</span>
      <span class="badge text-bg-secondary">FIFO wait queue</span>
      <span class="badge text-bg-secondary">Fence token</span>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="lock-before">
    <h2 class="h3" id="lock-before">Before you start</h2>
    <ul>
      <li>Choose a stable scope and name such as <code>thread-work.42</code>.</li>
      <li>Reuse the same request UUID when retrying one acquisition.</li>
      <li>Choose a 5-300 second lease and plan to heartbeat at about one third of that interval.</li>
      <li>Make the target atomically reject stale fence tokens, or use its native lock.</li>
      <li>Keep recoverable progress in Git and threads.</li>
    </ul>
  </section>

  <section class="mb-4" aria-labelledby="lock-semantics">
    <h2 class="h3" id="lock-semantics">Know who owns the lock</h2>
    <div class="row g-3">
      <div class="col-12 col-lg-4"><div class="card h-100"><div class="card-body"><h3 class="h5">Same identity</h3><p class="mb-0">Two tokens or processes authenticated as the same user are one owner. Acquisitions are reentrant, share a fence token, increase hold depth, and require balanced ticket releases.</p></div></div></div>
      <div class="col-12 col-lg-4"><div class="card h-100"><div class="card-body"><h3 class="h5">Distinct identities</h3><p class="mb-0">A different user contends or joins the FIFO queue. Promotion creates a newer fence token.</p></div></div></div>
      <div class="col-12 col-lg-4"><div class="card h-100"><div class="card-body"><h3 class="h5">External system</h3><p class="mb-0">Pearing cannot cancel running code. The target must enforce fencing or its own lock.</p></div></div></div>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="lock-workflow">
    <h2 class="h3" id="lock-workflow">The workflow</h2>
    <ol>
      <li class="mb-2"><strong>Derive one key.</strong> Map the same work to the same scope and lock name.</li>
      <li class="mb-2"><strong>Acquire idempotently.</strong> Reuse the request UUID after an uncertain response.</li>
      <li class="mb-2"><strong>Handle the result.</strong> Holders proceed, waiters poll, contenders back off, and rejected deadlocks abandon the newest wait.</li>
      <li class="mb-2"><strong>Read current state.</strong> Ownership does not prove that work remains.</li>
      <li class="mb-2"><strong>Heartbeat.</strong> Extend long leases and stop after expiry or a failed heartbeat.</li>
      <li class="mb-2"><strong>Fence writes.</strong> Compare the returned token atomically where the side effect occurs.</li>
      <li><strong>Release every acquisition.</strong> Release held tickets and cancel unused waiters.</li>
    </ol>
  </section>

  <section class="mb-4" aria-labelledby="lock-try">
    <h2 class="h3" id="lock-try">Try it with the CLI</h2>
    <div class="bg-light border rounded p-3">
      <pre class="mb-0"><code>pearing-cli acquire-lock thread-work.42 \
  --request-uuid e41b7608-1fe8-4f54-a5f3-67e8605f480c \
  --lease-seconds 60 \
  --wait-seconds 30 \
  --repo teams/platform/website

pearing-cli get-lock-ticket thread-work.42 \
  6bb65939-0db9-4fe2-83a7-ff6dfc3b00af \
  --repo teams/platform/website

pearing-cli heartbeat-lock-ticket thread-work.42 \
  6bb65939-0db9-4fe2-83a7-ff6dfc3b00af \
  --lease-seconds 60 \
  --repo teams/platform/website

pearing-cli release-lock-ticket thread-work.42 \
  6bb65939-0db9-4fe2-83a7-ff6dfc3b00af \
  --repo teams/platform/website</code></pre>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="lock-interface">
    <h2 class="h3" id="lock-interface">Using another interface</h2>
    <p>Acquire the same lock through MCP:</p>
    <div class="bg-light border rounded p-3 mb-3">
      <pre class="mb-0"><code>Tool: acquire_lock
Arguments:
{
  "repo": "teams/platform/website",
  "lock_name": "thread-work.42",
  "request_uuid": "e41b7608-1fe8-4f54-a5f3-67e8605f480c",
  "lease_seconds": 60,
  "wait_seconds": 30
}</code></pre>
    </div>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/locks">Lock tools MCP</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/locks">Lease locks API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/locks">Locks CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/guides/events-and-activity">Events and activity guide</a>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="lock-success">
    <h2 class="h3" id="lock-success">What success looks like</h2>
    <ul class="mb-0">
      <li>All responders derive one key and reuse one request UUID per attempt.</li>
      <li>One identity holds the lock while other identities wait in FIFO order.</li>
      <li>The holder heartbeats, reads current state, records progress, and releases every ticket.</li>
      <li>A promoted identity receives a newer fence token and checks whether work remains.</li>
      <li>The target rejects stale lower fence tokens or provides its own lock.</li>
    </ul>
  </section>

  <div class="alert alert-warning mb-4" role="note">
    <h2 class="h5 alert-heading">Common mistake</h2>
    <p class="mb-0">
      A Pearing lock is not a distributed transaction and lease expiry does not stop stale external work.
      Without atomic fencing or a native target-system lock, an expired holder can still commit a side effect.
    </p>
  </div>

  <section class="mb-4" aria-labelledby="lock-recovery">
    <h2 class="h3" id="lock-recovery">Failure and recovery</h2>
    <div class="accordion" id="lock-recovery-list">
      <div class="accordion-item">
        <h3 class="accordion-header" id="lock-expiry-heading"><button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#lock-expiry-body" aria-expanded="true" aria-controls="lock-expiry-body">The lease expires or heartbeat reports the ticket gone</button></h3>
        <div id="lock-expiry-body" class="accordion-collapse collapse show" aria-labelledby="lock-expiry-heading" data-bs-parent="#lock-recovery-list"><div class="accordion-body">Stop using the old ticket. Write only if the target atomically accepts its fence. A newer holder must read durable state before continuing.</div></div>
      </div>
      <div class="accordion-item">
        <h3 class="accordion-header" id="lock-wait-heading"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#lock-wait-body" aria-expanded="false" aria-controls="lock-wait-body">A waiter times out, is cancelled, or is promoted</button></h3>
        <div id="lock-wait-body" class="accordion-collapse collapse" aria-labelledby="lock-wait-heading" data-bs-parent="#lock-recovery-list"><div class="accordion-body">Inspect the ticket state. A promoted holder must revalidate because the previous owner may have completed the work.</div></div>
      </div>
      <div class="accordion-item">
        <h3 class="accordion-header" id="lock-retry-heading"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#lock-retry-body" aria-expanded="false" aria-controls="lock-retry-body">The acquire response is uncertain or access is revoked</button></h3>
        <div id="lock-retry-body" class="accordion-collapse collapse" aria-labelledby="lock-retry-heading" data-bs-parent="#lock-recovery-list"><div class="accordion-body">Retry with the same request UUID. If access changed, stop new work. The ticket owner can still release the known ticket.</div></div>
      </div>
    </div>
  </section>

  <section aria-labelledby="lock-reference">
    <h2 class="h3" id="lock-reference">Related reference</h2>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/locks">Lease locks API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/locks">Locks CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/locks">Lock tools MCP</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/guides/threads-and-pulls">Threads and pulls guide</a>
    </div>
  </section>
{% endblock %}