seqevi 0.3.5__tar.gz → 0.4.0__tar.gz

{seqevi-0.3.5 → seqevi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seqevi
-Version: 0.3.5
+Version: 0.4.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,30 +45,53 @@ single-file DuckDB result for the current FASTA.
 
 ## Status
 
-The target architecture and v1.1 result contracts are approved. The SeqEvi
-0.3.5 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.
+The source tree is a SeqEvi 0.4.0 release candidate. It implements strict
+protein sequence identity, local SQLite/POSIX and shared HTTP/PostgreSQL Stores
+with POSIX or explicit native OCI artifact storage, exact cache-miss
+orchestration, Linux external-tool containment, and immutable single-file
+DuckDB results. Python 3.12 or newer is required; direct adapter execution
+requires Linux. SeqEvi 0.4.0 has not been tagged or published as a Python or
+GitHub release, deployed to production, or used to migrate historical bytes.
 
-SeqEvi 0.3.5 provides managed setup for dbCAN only. The `eggnog` and
+The 0.4.0 candidate 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)
-preserves the incomplete original public-user run and its subsequent acceptance
-decision. In particular, a repeat pull from that run's site is a deferred
-transport check rather than a 0.2.0 release blocker.
-
-The `interpro-pfam` and eggNOG-mapper 2.x `eggnog` adapters are implemented with
-native-output validation and fixture parity coverage. The eggNOG adapter passes
-direct parity against eggNOG-mapper 2.1.13 and eggNOG DB 5.0.2. The InterPro
-adapter passes direct parity against InterProScan 5.77-108.0 with InterPro data
-108.0 and Pfam 38.1. The Phase 5 shared Store service, HTTP client, streamed
-POSIX artifacts, and PostgreSQL persistence are implemented and covered by
-local/shared plus provisioned PostgreSQL integration tests. Phase 6 resource
-locks avoid repeated hashing of large immutable database files and provide an
-explicit full-content verification command. Annotation now uses atomic FASTA
-staging, file-backed artifacts, bounded Store batches, adapter-native Parquet
-artifacts, and an operational thread setting.
+host profiles; managed setup for them is later feature work.
+
+> **Known incomplete or unavailable work:** the original managed dbCAN public-
+> user Slice D run remains incomplete; managed dispatch has no claim-before-OCI
+> path, so D5 is unavailable; InterPro v2 target-Store refresh remains open;
+> and global cache seeding is incomplete. See the
+> [documentation index](docs/README.md) for the governing records. None of
+> these states is represented as a pass.
+
+The `eggnog`, `interpro-pfam`, and `dbcan-cazyme` adapters preserve their native
+schemas and have accepted direct-runtime parity evidence. Shared Store,
+resource-lock, batching, and result-publication details are routed from the
+[current system architecture](docs/architecture/20260825-v1.0-current-system-architecture.md).
+
+## Release Channels
+
+SeqEvi treats repository CI, nightly packages, version tags, GitHub Releases,
+PyPI publication, and the dbCAN runtime image as distinct states:
+
+- pull requests and ordinary pushes run CI but do not publish;
+- an off-minute daily or manually dispatched nightly validates exact `main`
+  and retains SHA-named wheel/sdist artifacts for 14 days without publishing;
+- an immutable canonical `vX.Y.Z` tag is a validation candidate only and tag
+  push alone never publishes;
+- publishing a stable, non-prerelease GitHub Release for that exact tag starts
+  the separately gated PyPI Trusted Publishing path;
+- PyPI publication completes only after the external project/version/files are
+  read back successfully; GitHub Release publication necessarily precedes that
+  eventual completion; and
+- dbCAN OCI image publication remains an independent, manual dispatch with
+  exact source-revision tags and digest readback.
+
+Untagged builds use a PEP 440 development version derived from the most recent
+canonical tag, commit distance, and source revision. Installed distribution
+metadata, `seqevi.__version__`, and `seqevi --version` report one identity.
+There is no TestPyPI or release-candidate publishing channel in the current
+contract.
 
 ## Why SeqEvi
 
@@ -134,8 +157,8 @@ seqevi setup dbcan-cazyme \
 `--dry-run` never mutates state. `--yes` pulls the immutable image only when
 needed, verifies the caller-owned four-file resource, creates `seqevi.lock`
 when the resource permits it, runs an ephemeral read-only smoke, and publishes
-the v2 profile atomically. It never downloads or copies the database. Slice C
-now dispatches a managed dbCAN annotation through an ephemeral Docker
+the v2 profile atomically. It never downloads or copies the database. A managed
+dbCAN annotation runs through an ephemeral Docker
 container with the same caller UID/GID, read-only FASTA/resource mounts and a
 local-Store `--network none` boundary:
 
@@ -147,6 +170,13 @@ seqevi annotate \
   --output results/dbcan.duckdb
 ```
 
+The bundled managed kit and its selectable digest are unchanged. Separately,
+an immutable SeqEvi 0.3.5 revision image was automatically published at
+`ghcr.io/fuqingzh/seqevi-dbcan@sha256:1914939f1776fee3faac5241fc84f99f4534f37e20cc4d4d48eedf491c38488a`
+from merged revision `f7781c4ce7d642ef46619e6f02c7be3745803ca4`. That
+publication did not register a new managed kit or publish SeqEvi 0.4.0; image
+publication now requires an explicit workflow dispatch.
+
 The dispatcher and cleanup boundary are covered by fixture tests. Real
 direct-candidate versus managed-v2 scientific equality and later-process replay
 passed the release gate. A validation harness used an immutable local image ID
@@ -240,9 +270,11 @@ seqevi resource verify \
 - Exact, immutable evidence keys.
 - Explicit `eggnog`, `interpro-pfam`, and official-runtime-validated
   `dbcan-cazyme` adapters. dbCAN direct/local/shared scientific acceptance is
-  complete; publishing the managed runtime image remains separate work, and
-  annotation databases remain caller supplied.
-- Local SQLite/POSIX Store and shared PostgreSQL/POSIX Store service.
+  complete. The bundled managed kit is unchanged; the separately published
+  immutable 0.3.5 revision image is not a new selectable kit. Annotation
+  databases remain caller supplied.
+- Local SQLite/POSIX Store and shared PostgreSQL Store with legacy POSIX or
+  explicitly configured native OCI artifacts.
 - One self-describing DuckDB result per invocation; adapter-native normalized
   evidence remains Parquet inside the incremental Store.
 
@@ -252,31 +284,13 @@ schemas.
 
 ## Documentation
 
-Start with [the documentation index](docs/README.md).
-
-- [Architecture overview](docs/architecture/20260720-v1.0-seqevi-architecture.md)
-- [Sequence and evidence contract](docs/architecture/20260804-v1.1-sequence-evidence-contract.md)
-- [Adapter contract](docs/architecture/20260804-v1.1-adapter-contract.md)
-- [Result consumption contract](docs/architecture/20260804-v1.1-result-consumption-contract.md)
-- [Execution profile contract](docs/architecture/20260724-v1.0-execution-profile-contract.md)
-- [Storage and deployment architecture](docs/architecture/20260729-v1.1-storage-deployment-architecture.md)
-- [MVP implementation plan](docs/implementation-plan/20260720-v1.0-mvp-implementation-plan.md)
-- [Execution profile implementation plan](docs/implementation-plan/20260724-v1.0-execution-profile-implementation-plan.md)
-- [Validation strategy](docs/testing/20260720-v1.0-validation-strategy.md)
-- [Annotate runtime and bounded-memory plan](docs/implementation-plan/20260722-v1.0-annotate-bounded-memory-plan.md)
-- [Bounded-memory and operational performance](docs/benchmarks/20260722-v1.0-bounded-memory-performance.md)
-- [InterProScan Pfam runtime validation](docs/benchmarks/20260723-v1.0-interproscan-runtime-validation.md)
-- [dbCAN CAZyme adapter implementation plan](docs/implementation-plan/20260804-v1.0-dbcan-cazyme-adapter-implementation-plan.md)
-- [DuckDB result-consumption runtime acceptance](docs/benchmarks/20260805-v1.0-result-consumption-runtime-acceptance.md)
-- [dbCAN runtime image release review](docs/architecture/20260805-v1.1-dbcan-runtime-image-release-review.md)
-
-Accepted managed-boundary documents; Slice B setup and smoke plus Slice C OCI
-execution and real candidate acceptance are implemented, while v1 profiles
-remain compatible:
-
-- [Managed adapter onboarding roadmap v1.1](docs/implementation-plan/20260805-v1.1-managed-adapter-onboarding-implementation-plan.md)
-- [Managed-distribution architecture v1.2](docs/architecture/20260806-v1.2-managed-adapter-distribution-architecture.md)
-- [Execution profile v2.2 contract](docs/architecture/20260806-v2.2-execution-profile-contract.md)
+Start with the [documentation index](docs/README.md), the
+[current system architecture](docs/architecture/20260825-v1.0-current-system-architecture.md),
+or the [first-annotation guide](docs/how-to-guides/first-annotation.md).
+
+The index owns the current contract map, active work, incomplete evidence,
+operations, and historical navigation. Superseded architecture is retained in
+the [documentation archive](docs/archive/README.md), not mixed into onboarding.
 
 ## Python And Result Discovery
 
@@ -319,18 +333,17 @@ produce the new result file.
 
 ## External Tools
 
-Annotation runtimes and databases are supplied by the user. The current CLI has
-no `seqevi setup` command. SeqEvi v1 targets
+Annotation runtimes and databases are normally supplied by the user. SeqEvi
+targets
 [eggNOG-mapper](https://github.com/eggnogdb/eggnog-mapper) and
 [InterProScan](https://www.ebi.ac.uk/interpro/interproscan.html) with the Pfam
 application, and [dbCAN](https://github.com/bcb-unl/run_dbcan) for protein-level
-CAZyme annotation. A future managed path may publish a SeqEvi-maintained runtime
-image built from locked upstream inputs after runtime compliance review; it would
-not be an upstream-official image. Annotation databases remain separate and
-are never bundled in the wheel or runtime image. The proposed managed path
-uses a public, digest-pinned
-`ghcr.io/fuqingzh/seqevi-dbcan` runtime package; callers continue to provide the
-database path, and internal registry mirrors remain deployment policy.
+CAZyme annotation. Managed `seqevi setup` is implemented only for dbCAN using a
+public, digest-pinned `ghcr.io/fuqingzh/seqevi-dbcan` runtime image built from
+locked upstream inputs. It is SeqEvi-maintained, not an upstream-official dbCAN
+image. Callers still provide the database path; annotation databases are never
+bundled in the wheel or runtime image, and internal registry mirrors remain
+deployment policy.
 
 ## License
 

{seqevi-0.3.5 → seqevi-0.4.0}/README.md

@@ -10,30 +10,53 @@ single-file DuckDB result for the current FASTA.
 
 ## Status
 
-The target architecture and v1.1 result contracts are approved. The SeqEvi
-0.3.5 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.3.5 provides managed setup for dbCAN only. The `eggnog` and
+The source tree is a SeqEvi 0.4.0 release candidate. It implements strict
+protein sequence identity, local SQLite/POSIX and shared HTTP/PostgreSQL Stores
+with POSIX or explicit native OCI artifact storage, exact cache-miss
+orchestration, Linux external-tool containment, and immutable single-file
+DuckDB results. Python 3.12 or newer is required; direct adapter execution
+requires Linux. SeqEvi 0.4.0 has not been tagged or published as a Python or
+GitHub release, deployed to production, or used to migrate historical bytes.
+
+The 0.4.0 candidate 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)
-preserves the incomplete original public-user run and its subsequent acceptance
-decision. In particular, a repeat pull from that run's site is a deferred
-transport check rather than a 0.2.0 release blocker.
-
-The `interpro-pfam` and eggNOG-mapper 2.x `eggnog` adapters are implemented with
-native-output validation and fixture parity coverage. The eggNOG adapter passes
-direct parity against eggNOG-mapper 2.1.13 and eggNOG DB 5.0.2. The InterPro
-adapter passes direct parity against InterProScan 5.77-108.0 with InterPro data
-108.0 and Pfam 38.1. The Phase 5 shared Store service, HTTP client, streamed
-POSIX artifacts, and PostgreSQL persistence are implemented and covered by
-local/shared plus provisioned PostgreSQL integration tests. Phase 6 resource
-locks avoid repeated hashing of large immutable database files and provide an
-explicit full-content verification command. Annotation now uses atomic FASTA
-staging, file-backed artifacts, bounded Store batches, adapter-native Parquet
-artifacts, and an operational thread setting.
+host profiles; managed setup for them is later feature work.
+
+> **Known incomplete or unavailable work:** the original managed dbCAN public-
+> user Slice D run remains incomplete; managed dispatch has no claim-before-OCI
+> path, so D5 is unavailable; InterPro v2 target-Store refresh remains open;
+> and global cache seeding is incomplete. See the
+> [documentation index](docs/README.md) for the governing records. None of
+> these states is represented as a pass.
+
+The `eggnog`, `interpro-pfam`, and `dbcan-cazyme` adapters preserve their native
+schemas and have accepted direct-runtime parity evidence. Shared Store,
+resource-lock, batching, and result-publication details are routed from the
+[current system architecture](docs/architecture/20260825-v1.0-current-system-architecture.md).
+
+## Release Channels
+
+SeqEvi treats repository CI, nightly packages, version tags, GitHub Releases,
+PyPI publication, and the dbCAN runtime image as distinct states:
+
+- pull requests and ordinary pushes run CI but do not publish;
+- an off-minute daily or manually dispatched nightly validates exact `main`
+  and retains SHA-named wheel/sdist artifacts for 14 days without publishing;
+- an immutable canonical `vX.Y.Z` tag is a validation candidate only and tag
+  push alone never publishes;
+- publishing a stable, non-prerelease GitHub Release for that exact tag starts
+  the separately gated PyPI Trusted Publishing path;
+- PyPI publication completes only after the external project/version/files are
+  read back successfully; GitHub Release publication necessarily precedes that
+  eventual completion; and
+- dbCAN OCI image publication remains an independent, manual dispatch with
+  exact source-revision tags and digest readback.
+
+Untagged builds use a PEP 440 development version derived from the most recent
+canonical tag, commit distance, and source revision. Installed distribution
+metadata, `seqevi.__version__`, and `seqevi --version` report one identity.
+There is no TestPyPI or release-candidate publishing channel in the current
+contract.
 
 ## Why SeqEvi
 
@@ -99,8 +122,8 @@ seqevi setup dbcan-cazyme \
 `--dry-run` never mutates state. `--yes` pulls the immutable image only when
 needed, verifies the caller-owned four-file resource, creates `seqevi.lock`
 when the resource permits it, runs an ephemeral read-only smoke, and publishes
-the v2 profile atomically. It never downloads or copies the database. Slice C
-now dispatches a managed dbCAN annotation through an ephemeral Docker
+the v2 profile atomically. It never downloads or copies the database. A managed
+dbCAN annotation runs through an ephemeral Docker
 container with the same caller UID/GID, read-only FASTA/resource mounts and a
 local-Store `--network none` boundary:
 
@@ -112,6 +135,13 @@ seqevi annotate \
   --output results/dbcan.duckdb
 ```
 
+The bundled managed kit and its selectable digest are unchanged. Separately,
+an immutable SeqEvi 0.3.5 revision image was automatically published at
+`ghcr.io/fuqingzh/seqevi-dbcan@sha256:1914939f1776fee3faac5241fc84f99f4534f37e20cc4d4d48eedf491c38488a`
+from merged revision `f7781c4ce7d642ef46619e6f02c7be3745803ca4`. That
+publication did not register a new managed kit or publish SeqEvi 0.4.0; image
+publication now requires an explicit workflow dispatch.
+
 The dispatcher and cleanup boundary are covered by fixture tests. Real
 direct-candidate versus managed-v2 scientific equality and later-process replay
 passed the release gate. A validation harness used an immutable local image ID
@@ -205,9 +235,11 @@ seqevi resource verify \
 - Exact, immutable evidence keys.
 - Explicit `eggnog`, `interpro-pfam`, and official-runtime-validated
   `dbcan-cazyme` adapters. dbCAN direct/local/shared scientific acceptance is
-  complete; publishing the managed runtime image remains separate work, and
-  annotation databases remain caller supplied.
-- Local SQLite/POSIX Store and shared PostgreSQL/POSIX Store service.
+  complete. The bundled managed kit is unchanged; the separately published
+  immutable 0.3.5 revision image is not a new selectable kit. Annotation
+  databases remain caller supplied.
+- Local SQLite/POSIX Store and shared PostgreSQL Store with legacy POSIX or
+  explicitly configured native OCI artifacts.
 - One self-describing DuckDB result per invocation; adapter-native normalized
   evidence remains Parquet inside the incremental Store.
 
@@ -217,31 +249,13 @@ schemas.
 
 ## Documentation
 
-Start with [the documentation index](docs/README.md).
-
-- [Architecture overview](docs/architecture/20260720-v1.0-seqevi-architecture.md)
-- [Sequence and evidence contract](docs/architecture/20260804-v1.1-sequence-evidence-contract.md)
-- [Adapter contract](docs/architecture/20260804-v1.1-adapter-contract.md)
-- [Result consumption contract](docs/architecture/20260804-v1.1-result-consumption-contract.md)
-- [Execution profile contract](docs/architecture/20260724-v1.0-execution-profile-contract.md)
-- [Storage and deployment architecture](docs/architecture/20260729-v1.1-storage-deployment-architecture.md)
-- [MVP implementation plan](docs/implementation-plan/20260720-v1.0-mvp-implementation-plan.md)
-- [Execution profile implementation plan](docs/implementation-plan/20260724-v1.0-execution-profile-implementation-plan.md)
-- [Validation strategy](docs/testing/20260720-v1.0-validation-strategy.md)
-- [Annotate runtime and bounded-memory plan](docs/implementation-plan/20260722-v1.0-annotate-bounded-memory-plan.md)
-- [Bounded-memory and operational performance](docs/benchmarks/20260722-v1.0-bounded-memory-performance.md)
-- [InterProScan Pfam runtime validation](docs/benchmarks/20260723-v1.0-interproscan-runtime-validation.md)
-- [dbCAN CAZyme adapter implementation plan](docs/implementation-plan/20260804-v1.0-dbcan-cazyme-adapter-implementation-plan.md)
-- [DuckDB result-consumption runtime acceptance](docs/benchmarks/20260805-v1.0-result-consumption-runtime-acceptance.md)
-- [dbCAN runtime image release review](docs/architecture/20260805-v1.1-dbcan-runtime-image-release-review.md)
-
-Accepted managed-boundary documents; Slice B setup and smoke plus Slice C OCI
-execution and real candidate acceptance are implemented, while v1 profiles
-remain compatible:
-
-- [Managed adapter onboarding roadmap v1.1](docs/implementation-plan/20260805-v1.1-managed-adapter-onboarding-implementation-plan.md)
-- [Managed-distribution architecture v1.2](docs/architecture/20260806-v1.2-managed-adapter-distribution-architecture.md)
-- [Execution profile v2.2 contract](docs/architecture/20260806-v2.2-execution-profile-contract.md)
+Start with the [documentation index](docs/README.md), the
+[current system architecture](docs/architecture/20260825-v1.0-current-system-architecture.md),
+or the [first-annotation guide](docs/how-to-guides/first-annotation.md).
+
+The index owns the current contract map, active work, incomplete evidence,
+operations, and historical navigation. Superseded architecture is retained in
+the [documentation archive](docs/archive/README.md), not mixed into onboarding.
 
 ## Python And Result Discovery
 
@@ -284,18 +298,17 @@ produce the new result file.
 
 ## External Tools
 
-Annotation runtimes and databases are supplied by the user. The current CLI has
-no `seqevi setup` command. SeqEvi v1 targets
+Annotation runtimes and databases are normally supplied by the user. SeqEvi
+targets
 [eggNOG-mapper](https://github.com/eggnogdb/eggnog-mapper) and
 [InterProScan](https://www.ebi.ac.uk/interpro/interproscan.html) with the Pfam
 application, and [dbCAN](https://github.com/bcb-unl/run_dbcan) for protein-level
-CAZyme annotation. A future managed path may publish a SeqEvi-maintained runtime
-image built from locked upstream inputs after runtime compliance review; it would
-not be an upstream-official image. Annotation databases remain separate and
-are never bundled in the wheel or runtime image. The proposed managed path
-uses a public, digest-pinned
-`ghcr.io/fuqingzh/seqevi-dbcan` runtime package; callers continue to provide the
-database path, and internal registry mirrors remain deployment policy.
+CAZyme annotation. Managed `seqevi setup` is implemented only for dbCAN using a
+public, digest-pinned `ghcr.io/fuqingzh/seqevi-dbcan` runtime image built from
+locked upstream inputs. It is SeqEvi-maintained, not an upstream-official dbCAN
+image. Callers still provide the database path; annotation databases are never
+bundled in the wheel or runtime image, and internal registry mirrors remain
+deployment policy.
 
 ## License
 

{seqevi-0.3.5 → seqevi-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "seqevi"
-version = "0.3.5"
+dynamic = []
 description = "Content-addressed, reusable protein sequence annotation evidence."
 authors = [
     { name = "Fuqing Zhang", email = "fu.qing.zhang.work@gmail.com" },
@@ -31,6 +31,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Bio-Informatics",
 ]
 license = "MIT"
+version = "0.4.0"
 
 [project.urls]
 Homepage = "https://github.com/FuqingZh/seqevi"
@@ -64,11 +65,19 @@ dev = [
     "pytest-timeout>=2.4,<3",
     "pytest-xdist>=3.8,<4",
     "ruff>=0.15,<0.16",
+    "packaging<27,>=25",
+    "twine<7,>=6.2",
 ]
 
 [tool.pdm]
 distribution = true
 
+[tool.pdm.version]
+source = "scm"
+tag_filter = "v[0-9]*.[0-9]*.[0-9]*"
+tag_regex = "^v(?P<version>(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*))$"
+version_format = "scripts.version:format_version"
+
 [tool.pdm.scripts]
 format = "ruff format ."
 format-check = "ruff format --check ."

{seqevi-0.3.5 → seqevi-0.4.0}/src/seqevi/__init__.py

@@ -1,6 +1,9 @@
 """Content-addressed protein sequence annotation evidence."""
 
-__version__ = "0.3.5"
+from importlib.metadata import version
+
+
+__version__ = version("seqevi")
 
 from .api import annotate, scan_annotations
 

{seqevi-0.3.5 → seqevi-0.4.0}/src/seqevi/annotate.py

@@ -123,11 +123,17 @@ class _MeasuringToolRunner(ToolRunner):
         *,
         timeout_seconds: float | None = None,
         cancellation_signal: threading.Event | None = None,
+        output_limit_bytes: int | None = None,
     ) -> ToolRunResult:
         result = self.delegate.run(
             command,
             timeout_seconds=timeout_seconds,
             cancellation_signal=cancellation_signal or self.cancellation_signal,
+            **(
+                {"output_limit_bytes": output_limit_bytes}
+                if output_limit_bytes is not None
+                else {}
+            ),
         )
         self.duration_seconds += result.duration_seconds
         return result

{seqevi-0.3.5 → seqevi-0.4.0}/src/seqevi/api.py

@@ -35,6 +35,7 @@ from .progress import (
 )
 from .result import RESULT_FORMAT_VERSION, scan_annotations as _scan_annotations
 from .store import open_evidence_store
+from .store.oci import OciClientFiles
 
 
 @dataclass(frozen=True, slots=True)
@@ -78,6 +79,8 @@ def annotate(
     store: str | Path | None = None,
     threads: int | None = None,
     timeout_seconds: float | None = None,
+    oci_registry_config: str | Path | None = None,
+    oci_registry_ca_file: str | Path | None = None,
 ) -> duckdb.DuckDBPyRelation:
     """Annotate a protein FASTA and return its native DuckDB relation.
 
@@ -92,6 +95,9 @@ def annotate(
         store: Local Store path or shared Store URL.
         threads: Operational worker-thread override.
         timeout_seconds: Optional external-tool timeout.
+        oci_registry_config: Optional Docker/ORAS registry config file for one
+            OCI-backed shared Store invocation. It is never persisted in a profile.
+        oci_registry_ca_file: Optional PEM trust anchor for that registry.
 
     Returns:
         The `main.annotations` DuckDB relation. It keeps the read-only result
@@ -127,6 +133,8 @@ def annotate(
         store=store,
         threads=threads,
         timeout_seconds=timeout_seconds,
+        oci_registry_config=oci_registry_config,
+        oci_registry_ca_file=oci_registry_ca_file,
     )
     return invocation.relation
 
@@ -170,9 +178,15 @@ def _run_annotation_application(
     store: str | Path | None,
     threads: int | None,
     timeout_seconds: float | None,
+    oci_registry_config: str | Path | None = None,
+    oci_registry_ca_file: str | Path | None = None,
     adapter_factory: Callable[[AdapterConfiguration], AnnotationAdapter] | None = None,
     progress_sink: ProgressSink | None = None,
 ) -> AnnotationInvocation:
+    oci_files = _resolve_oci_client_files(
+        oci_registry_config=oci_registry_config,
+        oci_registry_ca_file=oci_registry_ca_file,
+    )
     emit_progress(
         progress_sink,
         ProgressEvent(
@@ -207,6 +221,7 @@ def _run_annotation_application(
             store=inputs.store,
             threads=inputs.threads,
             timeout_seconds=inputs.timeout_seconds,
+            oci_files=oci_files,
         )
         emit_progress(
             progress_sink,
@@ -243,7 +258,7 @@ def _run_annotation_application(
         )
     )
     metadata = _result_metadata_template(configured_adapter)
-    with open_evidence_store(inputs.store) as evidence_store:
+    with open_evidence_store(inputs.store, oci_files=oci_files) as evidence_store:
         summary = run_annotation(
             fasta_path=fasta.expanduser().resolve(),
             output_dir=output.expanduser().resolve(),
@@ -290,6 +305,25 @@ def _run_annotation_application(
     return invocation
 
 
+def _resolve_oci_client_files(
+    *,
+    oci_registry_config: str | Path | None,
+    oci_registry_ca_file: str | Path | None,
+) -> OciClientFiles | None:
+    """Resolve invocation-only OCI client files without reading credentials."""
+
+    if oci_registry_config is None and oci_registry_ca_file is None:
+        return None
+    return OciClientFiles(
+        registry_config=(
+            Path(oci_registry_config) if oci_registry_config is not None else None
+        ),
+        ca_file=Path(oci_registry_ca_file)
+        if oci_registry_ca_file is not None
+        else None,
+    ).validated()
+
+
 def resolve_annotation_inputs(
     *,
     profile: str | None,