seqevi 0.2.0__tar.gz → 0.3.0__tar.gz

{seqevi-0.2.0 → seqevi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seqevi
-Version: 0.2.0
+Version: 0.3.0
 Summary: Content-addressed, reusable protein sequence annotation evidence.
 Author-Email: Fuqing Zhang <fu.qing.zhang.work@gmail.com>, FuqingZhang <103730099+FuqingZh@users.noreply.github.com>
 License-Expression: MIT
@@ -45,11 +45,11 @@ single-file DuckDB result for the current FASTA.
 ## Status
 
 The target architecture and v1.1 result contracts are approved. The SeqEvi
-0.2.0 source tree uses strict protein sequence identity, the single-host
+0.3.0 source tree uses strict protein sequence identity, the single-host
 SQLite/POSIX Store, the external tool runner, exact cache-miss orchestration,
 and atomic DuckDB result materialization.
 
-SeqEvi 0.2.0 provides managed setup for dbCAN only. The `eggnog` and
+SeqEvi 0.3.0 provides managed setup for dbCAN only. The `eggnog` and
 `interpro-pfam` adapters remain supported through explicit runtimes and named
 host profiles; managed setup for them is later feature work. The
 [Slice D gate record](docs/benchmarks/20260806-v1.4-dbcan-public-release-gate.md)
@@ -208,6 +208,9 @@ seqevi annotate \
 
 Shared deployments expose the same Store contract:
 
+The shared Store requires PostgreSQL 17 or newer so every mutation can enforce
+one cumulative transaction deadline inside the claim lease runway.
+
 ```bash
 seqevi serve \
   --database-url postgresql+psycopg://seqevi@postgres/seqevi \

{seqevi-0.2.0 → seqevi-0.3.0}/README.md

@@ -11,11 +11,11 @@ single-file DuckDB result for the current FASTA.
 ## Status
 
 The target architecture and v1.1 result contracts are approved. The SeqEvi
-0.2.0 source tree uses strict protein sequence identity, the single-host
+0.3.0 source tree uses strict protein sequence identity, the single-host
 SQLite/POSIX Store, the external tool runner, exact cache-miss orchestration,
 and atomic DuckDB result materialization.
 
-SeqEvi 0.2.0 provides managed setup for dbCAN only. The `eggnog` and
+SeqEvi 0.3.0 provides managed setup for dbCAN only. The `eggnog` and
 `interpro-pfam` adapters remain supported through explicit runtimes and named
 host profiles; managed setup for them is later feature work. The
 [Slice D gate record](docs/benchmarks/20260806-v1.4-dbcan-public-release-gate.md)
@@ -174,6 +174,9 @@ seqevi annotate \
 
 Shared deployments expose the same Store contract:
 
+The shared Store requires PostgreSQL 17 or newer so every mutation can enforce
+one cumulative transaction deadline inside the claim lease runway.
+
 ```bash
 seqevi serve \
   --database-url postgresql+psycopg://seqevi@postgres/seqevi \

{seqevi-0.2.0 → seqevi-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "seqevi"
-version = "0.2.0"
+version = "0.3.0"
 description = "Content-addressed, reusable protein sequence annotation evidence."
 authors = [
     { name = "Fuqing Zhang", email = "fu.qing.zhang.work@gmail.com" },

{seqevi-0.2.0 → seqevi-0.3.0}/src/seqevi/__init__.py

@@ -1,6 +1,6 @@
 """Content-addressed protein sequence annotation evidence."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from .api import annotate, scan_annotations
 

{seqevi-0.2.0 → seqevi-0.3.0}/src/seqevi/annotate.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+import os
 import shutil
 import sys
 import tempfile
+import threading
 import time
-from dataclasses import dataclass
 from collections.abc import Mapping
+from dataclasses import dataclass
 from datetime import UTC, datetime
 from itertools import batched
 from pathlib import Path
@@ -17,13 +19,15 @@ from . import __version__
 from .adapters.base import AdapterBatchResult, AnnotationAdapter
 from .errors import AnnotationError, OutputPackageError
 from .evidence import (
+    ClaimDisposition,
+    CommitOutcome,
     EvidenceCommit,
     EvidenceQuery,
     EvidenceSource,
     EvidenceStatus,
 )
 from .result import RESULT_FORMAT_VERSION, materialize_result_database
-from .runner import ToolCommand, ToolRunResult, ToolRunner
+from .runner import ToolCancelledError, ToolCommand, ToolRunResult, ToolRunner
 from .sequence import (
     SequenceIdentity,
     iter_staged_identities,
@@ -31,15 +35,25 @@ from .sequence import (
     iter_fasta_lines,
     stage_fasta,
 )
-from .store.contract import EvidenceStore
+from .store.contract import (
+    ClaimSession,
+    EvidenceStore,
+    is_claim_session_capable_store,
+)
 
 _STORE_BATCH_SIZE = 1_000
 _ANNOTATION_BATCH_SIZE = 10_000
+_CLAIM_RUNWAY_SECONDS = 5.0
 
 
 @dataclass(frozen=True, slots=True)
 class AnnotationMetrics:
-    """Operational measurements for one successful annotation invocation."""
+    """Operational measurements for one successful annotation invocation.
+
+    ``existing_finalizations`` counts proposed terminal records that a
+    ClaimSession resolved to immutable evidence already finalized by a peer.
+    It is observational and does not change computed/cache provenance.
+    """
 
     elapsed_seconds: float
     fasta_staging_seconds: float
@@ -56,6 +70,7 @@ class AnnotationMetrics:
     tool_batches: int
     unique_artifact_reads: int
     configured_threads: int
+    existing_finalizations: int = 0
 
 
 @dataclass(frozen=True, slots=True)
@@ -77,11 +92,19 @@ class _BatchMetrics:
     commit_batches: int
     adapter_seconds: float
     store_commit_seconds: float
+    peer_completed_sequence_ids: frozenset[str] = frozenset()
+    existing_finalizations: int = 0
 
 
 class _MeasuringToolRunner(ToolRunner):
-    def __init__(self, delegate: ToolRunner) -> None:
+    def __init__(
+        self,
+        delegate: ToolRunner,
+        *,
+        cancellation_signal: threading.Event | None = None,
+    ) -> None:
         self.delegate = delegate
+        self.cancellation_signal = cancellation_signal
         self.duration_seconds = 0.0
 
     def run(
@@ -89,8 +112,13 @@ class _MeasuringToolRunner(ToolRunner):
         command: ToolCommand,
         *,
         timeout_seconds: float | None = None,
+        cancellation_signal: threading.Event | None = None,
     ) -> ToolRunResult:
-        result = self.delegate.run(command, timeout_seconds=timeout_seconds)
+        result = self.delegate.run(
+            command,
+            timeout_seconds=timeout_seconds,
+            cancellation_signal=cancellation_signal or self.cancellation_signal,
+        )
         self.duration_seconds += result.duration_seconds
         return result
 
@@ -138,11 +166,41 @@ def run_annotation(
     store_lookup_seconds = 0.0
     adapter_seconds = 0.0
     store_commit_seconds = 0.0
+    existing_finalizations = 0
+    claim_session: ClaimSession | None = None
+    primary_failure: BaseException | None = None
+    close_failure: BaseException | None = None
+    published_output_identity: tuple[int, int] | None = None
+    published_output_marker: Path | None = None
+
+    def unlink_owned_output() -> None:
+        if published_output_identity is None or published_output_marker is None:
+            return
+        try:
+            current = output_dir.stat(follow_symlinks=False)
+            marker = published_output_marker.stat(follow_symlinks=False)
+        except FileNotFoundError:
+            return
+        if (current.st_dev, current.st_ino) == published_output_identity and (
+            marker.st_dev,
+            marker.st_ino,
+        ) == published_output_identity:
+            output_dir.unlink()
+
     try:
         keys_by_sequence_id = {}
         computed_ids: set[str] = set()
         pending_misses: list[SequenceIdentity] = []
-        tool_runner = _MeasuringToolRunner(runner or ToolRunner())
+        busy_queries: list[EvidenceQuery] = []
+        busy_retry_after: float | None = None
+        if is_claim_session_capable_store(store):
+            claim_session = store.claim_session().__enter__()
+        tool_runner = _MeasuringToolRunner(
+            runner or ToolRunner(),
+            cancellation_signal=(
+                claim_session.cancellation_signal if claim_session is not None else None
+            ),
+        )
 
         for identity_batch in batched(iter_staged_identities(stage), _STORE_BATCH_SIZE):
             queries = tuple(
@@ -153,16 +211,43 @@ def run_annotation(
                 (query.identity.sequence_id, query.key) for query in queries
             )
             lookup_started = time.perf_counter()
-            cached = store.lookup_many(queries)
+            if claim_session is not None:
+                claim_session.raise_if_lost()
+                decisions = claim_session.acquire_many(queries)
+                cached = {
+                    query.key: decision.record
+                    for query, decision in zip(queries, decisions, strict=True)
+                    if decision.disposition is ClaimDisposition.CACHED
+                }
+                for query, decision in zip(queries, decisions, strict=True):
+                    if decision.disposition is ClaimDisposition.ACQUIRED:
+                        assert decision.claim is not None
+                        pending_misses.append(query.identity)
+                    elif decision.disposition is ClaimDisposition.BUSY:
+                        busy_queries.append(query)
+                        assert decision.busy is not None
+                        busy_retry_after = (
+                            decision.busy.retry_after_seconds
+                            if busy_retry_after is None
+                            else min(
+                                busy_retry_after,
+                                decision.busy.retry_after_seconds,
+                            )
+                        )
+            else:
+                cached = store.lookup_many(queries)
             store_lookup_seconds += time.perf_counter() - lookup_started
             lookup_batches += 1
-            for query in queries:
-                if query.key not in cached:
-                    pending_misses.append(query.identity)
-                    computed_ids.add(query.identity.sequence_id)
+            if claim_session is None:
+                for query in queries:
+                    if query.key not in cached:
+                        pending_misses.append(query.identity)
             while len(pending_misses) >= _ANNOTATION_BATCH_SIZE:
                 annotation_identities = tuple(pending_misses[:_ANNOTATION_BATCH_SIZE])
                 del pending_misses[:_ANNOTATION_BATCH_SIZE]
+                computed_ids.update(
+                    identity.sequence_id for identity in annotation_identities
+                )
                 tool_batches += 1
                 batch_metrics = _run_annotation_batch(
                     identities=annotation_identities,
@@ -173,12 +258,18 @@ def run_annotation(
                     runner=tool_runner,
                     timeout_seconds=timeout_seconds,
                     threads=threads,
+                    claim_session=claim_session,
                 )
                 commit_batches += batch_metrics.commit_batches
                 adapter_seconds += batch_metrics.adapter_seconds
                 store_commit_seconds += batch_metrics.store_commit_seconds
+                existing_finalizations += batch_metrics.existing_finalizations
+                computed_ids.difference_update(
+                    batch_metrics.peer_completed_sequence_ids
+                )
 
         if pending_misses:
+            computed_ids.update(identity.sequence_id for identity in pending_misses)
             tool_batches += 1
             batch_metrics = _run_annotation_batch(
                 identities=tuple(pending_misses),
@@ -189,14 +280,72 @@ def run_annotation(
                 runner=tool_runner,
                 timeout_seconds=timeout_seconds,
                 threads=threads,
+                claim_session=claim_session,
             )
             commit_batches += batch_metrics.commit_batches
             adapter_seconds += batch_metrics.adapter_seconds
             store_commit_seconds += batch_metrics.store_commit_seconds
+            existing_finalizations += batch_metrics.existing_finalizations
+            computed_ids.difference_update(batch_metrics.peer_completed_sequence_ids)
+
+        while busy_queries:
+            time.sleep(busy_retry_after or 1.0)
+            next_retry_after: float | None = None
+            next_busy = []
+            acquired = []
+            assert claim_session is not None
+            for busy_batch in batched(busy_queries, _STORE_BATCH_SIZE):
+                reacquire_started = time.perf_counter()
+                claim_session.raise_if_lost()
+                decisions = claim_session.acquire_many(busy_batch)
+                store_lookup_seconds += time.perf_counter() - reacquire_started
+                lookup_batches += 1
+                for query, decision in zip(busy_batch, decisions, strict=True):
+                    if decision.disposition is ClaimDisposition.ACQUIRED:
+                        assert decision.claim is not None
+                        acquired.append(query.identity)
+                    elif decision.disposition is ClaimDisposition.BUSY:
+                        assert decision.busy is not None
+                        next_retry_after = (
+                            decision.busy.retry_after_seconds
+                            if next_retry_after is None
+                            else min(
+                                next_retry_after,
+                                decision.busy.retry_after_seconds,
+                            )
+                        )
+                        next_busy.append(query)
+            for acquired_batch in batched(acquired, _ANNOTATION_BATCH_SIZE):
+                computed_ids.update(identity.sequence_id for identity in acquired_batch)
+                tool_batches += 1
+                batch_metrics = _run_annotation_batch(
+                    identities=acquired_batch,
+                    batch_number=tool_batches,
+                    work_dir=work_dir,
+                    adapter=adapter,
+                    store=store,
+                    runner=tool_runner,
+                    timeout_seconds=timeout_seconds,
+                    threads=threads,
+                    claim_session=claim_session,
+                )
+                commit_batches += batch_metrics.commit_batches
+                adapter_seconds += batch_metrics.adapter_seconds
+                store_commit_seconds += batch_metrics.store_commit_seconds
+                existing_finalizations += batch_metrics.existing_finalizations
+                computed_ids.difference_update(
+                    batch_metrics.peer_completed_sequence_ids
+                )
+            busy_queries = next_busy
+            busy_retry_after = next_retry_after
 
+        if claim_session is not None:
+            claim_session.raise_if_lost()
         fetch_started = time.perf_counter()
         fetched_by_key = store.fetch_many(keys_by_sequence_id.values())
         store_fetch_seconds = time.perf_counter() - fetch_started
+        if claim_session is not None:
+            claim_session.raise_if_lost()
         missing_keys = set(keys_by_sequence_id.values()) - fetched_by_key.keys()
         if missing_keys:
             raise AnnotationError(
@@ -223,8 +372,17 @@ def run_annotation(
         metadata = dict(result_metadata or _default_result_metadata(adapter))
         metadata["InputDigest"] = stage.input_digest
         metadata.setdefault("CreatedAt", datetime.now(UTC).isoformat())
+        package_output = (
+            work_dir / "candidate-result.duckdb"
+            if claim_session is not None
+            else output_dir
+        )
+        if claim_session is not None:
+            claim_session.raise_if_lost()
+            if output_dir.exists():
+                raise AnnotationError(f"output path already exists: {output_dir}")
         materialize_result_database(
-            output_path=output_dir,
+            output_path=package_output,
             records=iter_staged_records(stage),
             input_record_count=stage.input_records,
             fetched_by_sequence_id=fetched_by_sequence_id,
@@ -240,18 +398,56 @@ def run_annotation(
                 "computed": len(computed_ids),
                 "hits": statuses.count(EvidenceStatus.HIT),
                 "no_hits": statuses.count(EvidenceStatus.NO_HIT),
+                "existing_finalizations": existing_finalizations,
             },
         )
+        if claim_session is not None:
+            try:
+                claim_session.raise_if_lost()
+                candidate = package_output.stat(follow_symlinks=False)
+                published_output_identity = (candidate.st_dev, candidate.st_ino)
+                published_output_marker = package_output
+                os.link(package_output, output_dir)
+                claim_session.raise_if_lost()
+            except BaseException:
+                unlink_owned_output()
+                raise
         package_seconds = time.perf_counter() - package_started
-    except Exception as error:
+    except BaseException as error:
+        primary_failure = error
+        if not isinstance(error, Exception):
+            raise
         raise AnnotationError(
             f"annotation failed; diagnostics retained at {work_dir}: {error}"
         ) from error
-    else:
-        shutil.rmtree(work_dir, ignore_errors=True)
     finally:
+        if claim_session is not None:
+            try:
+                claim_session.__exit__(None, None, None)
+            except BaseException as close_error:
+                if primary_failure is None:
+                    close_failure = close_error
+                else:
+                    primary_failure.add_note(
+                        f"ClaimSession cleanup also failed: {close_error!r}"
+                    )
         shutil.rmtree(stage.root, ignore_errors=True)
 
+    if close_failure is not None:
+        unlink_owned_output()
+        raise close_failure
+    if claim_session is not None:
+        try:
+            claim_session.raise_if_lost()
+        except BaseException as error:
+            unlink_owned_output()
+            if not isinstance(error, Exception):
+                raise
+            raise AnnotationError(
+                f"annotation failed; diagnostics retained at {work_dir}: {error}"
+            ) from error
+    shutil.rmtree(work_dir, ignore_errors=True)
+
     statuses = [fetched.record.status for fetched in fetched_by_sequence_id.values()]
     artifact_digests = {
         digest
@@ -286,6 +482,7 @@ def run_annotation(
             tool_batches=tool_batches,
             unique_artifact_reads=len(artifact_digests),
             configured_threads=threads,
+            existing_finalizations=existing_finalizations,
         ),
     )
 
@@ -340,36 +537,60 @@ def _run_annotation_batch(
     runner: ToolRunner,
     timeout_seconds: float | None,
     threads: int,
+    claim_session: ClaimSession | None = None,
 ) -> _BatchMetrics:
     batch_dir = work_dir / f"batch-{batch_number:06d}"
     batch_dir.mkdir()
     misses_fasta = batch_dir / "cache-misses.fasta"
+    if claim_session is not None:
+        claim_session.raise_if_lost()
     with misses_fasta.open("w", encoding="ascii", newline="\n") as handle:
         handle.writelines(iter_fasta_lines(identities))
     adapter_started = time.perf_counter()
-    batch = adapter.run_batch(
-        identities=identities,
-        input_fasta=misses_fasta,
-        work_dir=batch_dir,
-        runner=runner,
-        timeout_seconds=timeout_seconds,
-        threads=threads,
-    )
+    try:
+        batch = adapter.run_batch(
+            identities=identities,
+            input_fasta=misses_fasta,
+            work_dir=batch_dir,
+            runner=runner,
+            timeout_seconds=timeout_seconds,
+            threads=threads,
+        )
+    except ToolCancelledError:
+        if claim_session is not None:
+            claim_session.raise_if_lost()
+        raise
     adapter_seconds = time.perf_counter() - adapter_started
-    commits = _build_commits(
-        batch=batch,
-        identities=identities,
-        adapter=adapter,
-    )
+    if claim_session is not None:
+        claim_session.raise_if_lost()
+    commits = _build_commits(batch=batch, identities=identities, adapter=adapter)
     batches = 0
+    peer_completed_sequence_ids: set[str] = set()
+    existing_finalizations = 0
     commit_started = time.perf_counter()
     for commit_batch in batched(commits, _STORE_BATCH_SIZE):
-        store.commit_many(commit_batch)
-        batches += 1
+        if claim_session is None:
+            store.commit_many(commit_batch)
+            batches += 1
+        else:
+            claim_session.raise_if_lost()
+            outcomes = claim_session.finalize_many(commit_batch)
+            claim_session.raise_if_lost()
+            peer_completed_sequence_ids.update(
+                commit.identity.sequence_id
+                for commit, outcome in zip(commit_batch, outcomes, strict=True)
+                if outcome is CommitOutcome.EXISTING
+            )
+            existing_finalizations += sum(
+                outcome is CommitOutcome.EXISTING for outcome in outcomes
+            )
+            batches += 1
     return _BatchMetrics(
         commit_batches=batches,
         adapter_seconds=adapter_seconds,
         store_commit_seconds=time.perf_counter() - commit_started,
+        peer_completed_sequence_ids=frozenset(peer_completed_sequence_ids),
+        existing_finalizations=existing_finalizations,
     )