refactor: move object precondition contracts (#3547)

docs/architecture/crate-boundaries.md

@@ -95,6 +95,7 @@ Required `rustfs-storage-api` public re-exports:
 - `pub use error::{StorageErrorCode, StorageResult};`
 - `pub use multipart::{CompletePart, ListMultipartsInfo, ListPartsInfo, MultipartInfo, MultipartUploadResult, PartInfo};`
 - `pub use object::{HTTPPreconditions, HTTPRangeError, HTTPRangeSpec, ObjectLockRetentionOptions};`
+- `pub use object::{ObjectPreconditionError, ObjectPreconditionPart, ObjectPreconditionState};`
 - `pub use object::{VersionMarker, WalkVersionsSortOrder};`
 
 ECStore must keep compile-time coverage for both `StorageAdminApi` and the

docs/architecture/migration-progress.md

@@ -5,19 +5,18 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
 ## Current Context
 
 - Issue: [`rustfs/backlog#660`](https://github.com/rustfs/backlog/issues/660)
-- Branch: `overtrue/arch-object-list-helper-contracts`
-- Baseline: `overtrue/arch-range-contracts` at `829bc62095f0fd853747cd6d7d77f8558baf24a2`
-  over `origin/main` at `a9aba323c6512e6b99c3137258b97b6058075ce9`
+- Branch: `overtrue/arch-object-precondition-contracts`
+- Baseline: `overtrue/arch-object-list-helper-contracts` at `65b56e1fb4fa4c65c167e2f434bf5fcb2a0b0cd4f`
+  over `overtrue/arch-range-contracts` at `829bc62095f0fd853747cd6d7d77f8558baf24a2`
 - PR type for this branch: `api-extraction`
 - Runtime behavior changes: no external behavior change expected.
-- Rust code changes: move the pure `VersionMarker` and
-  `WalkVersionsSortOrder` list helper contracts into `rustfs-storage-api`,
-  then keep ECStore list/walk implementations and filemeta adaptation at the
-  ECStore boundary.
-- CI/script changes: extend migration guards for list helper public re-exports
-  and reject restoring the old ECStore-owned list helper definitions or
+- Rust code changes: move pure object HTTP precondition evaluation into
+  `rustfs-storage-api` as `ObjectPreconditionState`,
+  `ObjectPreconditionPart`, and `ObjectPreconditionError`, then keep
+  `ObjectOptions`, `ObjectInfo`, and ECStore error mapping in ECStore.
+- CI/script changes: extend migration guards for object precondition contract
   public re-exports.
-- Docs changes: record the list helper contract extraction slice.
+- Docs changes: record the object precondition contract extraction slice.
 
 ## Phase 0 Tasks
 
@@ -599,6 +598,27 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
     migration/layer guards, formatting, diff hygiene, Rust risk scan, and
     required three-expert review passed.
 
+- [x] `API-018` Move object precondition helper contracts.
+  - Completed slice: add `ObjectPreconditionState`,
+    `ObjectPreconditionPart`, and `ObjectPreconditionError` to
+    `rustfs-storage-api`; make ECStore `ObjectOptions::precondition_check`
+    adapt `ObjectInfo` into the shared pure contract and map the contract
+    result back to the existing ECStore errors.
+  - Acceptance: `rustfs-storage-api` exports the precondition helper contracts,
+    ECStore keeps `ObjectOptions` and `ObjectInfo`, and migration guards reject
+    dropping the public precondition contract re-export.
+  - Must preserve: requested-part validation, empty condition handling,
+    `If-None-Match`/`If-Modified-Since` `NotModified` behavior,
+    `If-Match`/`If-Unmodified-Since` `PreconditionFailed` behavior, wildcard
+    ETag matching, and ECStore error mapping.
+  - Risk defense: only pure precondition decision state and result contracts
+    cross into `rustfs-storage-api`; ECStore keeps object metadata adaptation,
+    storage error types, `ObjectOptions`, `ObjectInfo`, readers,
+    lifecycle/replication coupling, and storage implementation bodies.
+  - Verification: focused storage-api tests, ECStore/RustFS/downstream compile
+    checks, migration/layer guards, formatting, diff hygiene, Rust risk scan,
+    and required three-expert review passed.
+
 ## Phase 8 Background Controller Tasks
 
 - [x] `BGC-001` Inventory background services.
@@ -875,39 +895,43 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
 
 | Expert | Status | Notes |
 |---|---|---|
-| Quality/architecture | passed | Pure object list helper contracts now live in `rustfs-storage-api`; implementation-heavy list/walk contracts and ECStore behavior stay in ECStore. |
-| Migration preservation | passed | The slice changes helper type ownership and import paths only; null version marker parsing, first-entry version marker behavior, walk sort default, and ECStore filemeta/list behavior are unchanged. |
-| Testing/verification | passed | Focused storage-api/ECStore/RustFS/downstream compile checks, migration/layer guards, formatting, diff hygiene, Rust risk scan, and full `make pre-commit` passed. |
+| Quality/architecture | passed | Pure precondition decision state and result contracts now live in `rustfs-storage-api`; ECStore still owns object metadata adaptation and storage error mapping. |
+| Migration preservation | passed | Requested-part validation, ETag/date precondition priority, empty condition handling, and existing ECStore `Error` mapping are preserved. |
+| Testing/verification | passed | Focused storage-api/ECStore tests, compile checks, migration/layer guards, formatting, diff hygiene, Rust risk scan, and full `make pre-commit` passed. |
 
 ## Verification Notes
 
 Passed before push:
 
 - `cargo test -p rustfs-storage-api`: passed.
+- `cargo test -p rustfs-ecstore precondition_check_ignores_empty_etag_conditions`: passed.
 - `cargo check --tests -p rustfs-storage-api -p rustfs-ecstore -p rustfs -p rustfs-iam -p rustfs-scanner`: passed.
 - `./scripts/check_architecture_migration_rules.sh`: passed.
 - `./scripts/check_layer_dependencies.sh`: passed.
 - `cargo fmt --all --check`: passed.
 - `git diff --check`: passed.
-- Rust risk scan: no new production `unwrap`/`expect`, panic/todo markers,
-  `unsafe`, process-spawning calls, lossy casts, println/eprintln, or relaxed
-  ordering in added Rust lines; new `expect` calls are test-only assertions.
-- `make pre-commit`: passed.
+- Rust risk scan: no new `unwrap`/`expect`, panic/todo markers, `unsafe`,
+  process-spawning calls, lossy casts, println/eprintln, or relaxed ordering in
+  added Rust lines.
+- `make pre-commit`: passed; nextest reported 6164 tests passed and 111
+  skipped, and doctests passed.
 
 Notes:
 
 - This slice follows the range helper contract branch and keeps the old
   aggregate facade, bucket DTO, multipart DTO, bucket operation contract, object
-  helper, range helper, and list helper contract guards active.
-- The shared list marker/sort helper contracts are now owned by
-  `rustfs-storage-api`; ECStore keeps implementation-heavy object/list result
-  DTOs, walk options with filemeta filters, readers, lifecycle/replication, rio,
-  filemeta, and storage error contracts.
-- The slice does not alter list, walk, object, multipart, or bucket runtime
-  behavior.
+  helper, range helper, list helper, and object precondition contract guards
+  active.
+- The shared precondition helper contract is now owned by
+  `rustfs-storage-api`; ECStore keeps `ObjectOptions`, `ObjectInfo`, object
+  metadata adaptation, storage error mapping, readers, lifecycle/replication,
+  rio, filemeta, and implementation behavior.
+- The slice does not alter object, list, walk, multipart, bucket, or reader
+  runtime behavior.
 
 ## Handoff Notes
 
-- List helper contract cleanup is stacked on the range helper contract branch.
+- Object precondition contract cleanup is stacked on the list helper contract
+  branch.
 - After this lands, remaining storage work can continue by extracting larger
   low-coupling DTO slices or by narrowing remaining operation-group consumers.