feat(storage): configure minimum durable copies

docs/en/concepts/architecture.md

@@ -36,7 +36,7 @@ The key boundary is between the S3 response and Filecoin upload. When a write is
 
 - Confirmed S3 writes must survive async upload failures.
 - Object visibility and object storage progress are tracked separately.
-- Cache eviction only happens after the configured remote-copy policy is satisfied.
+- Cache eviction only happens after the bucket's cache-release threshold is met. By default that threshold is each upload's frozen replica target.
 - SynapS3 uses a single-node design and does not assume distributed coordination.
 
 ## What This Means for Operators

docs/en/concepts/filecoin-storage-flow.md

@@ -30,8 +30,8 @@ flowchart TD
 | `cached` | Object is durable locally and queued for upload. |
 | `uploading` | A background task is preparing remote storage or uploading bytes. |
 | `committing` | The provider has a piece ready and the commit step is in progress. |
-| `replicating` | At least one readable copy exists while target copies are still being completed. |
-| `stored` | Target remote copy policy is satisfied and metadata is available. |
+| `replicating` | At least one readable committed copy exists, but the bucket's minimum durable copies are not yet met. |
+| `stored` | The bucket's minimum durable copies are readable and committed; remaining target copies may still be syncing. |
 | `failed` | The active lifecycle step failed and may be retried. |
 | `cache_evicted` | Local cache has been removed after remote durability. |
 
@@ -54,12 +54,18 @@ Health checks record storage provider and local data set status. The dashboard u
 
 If an established provider becomes temporarily unavailable while the initial copies are still being stored, SynapS3 keeps using the other assigned writable copies. The unfinished copy waits without consuming retries and resumes automatically when the original provider becomes reachable again. SynapS3 does not automatically select a replacement provider. Repairing copies that became unavailable after storage completed remains part of the planned replica repair feature below.
 
+## Target and Minimum Replicas
+
+The target replica count is frozen when an upload starts. By default, **Release cache after** is **All replicas (strict)**: every target replica frozen for that upload must be readable and committed. A bucket can instead set an explicit count from 1 through the current target. An explicit count stays if Replicas later increases; lowering Replicas below that count is rejected until Release cache after is also lowered. **All replicas (strict)** follows each upload's frozen target. Once that threshold is met, the version becomes stored and its cache follows the configured eviction policy, while remaining replicas continue until the upload's target is reached. The dashboard keeps showing replica sync progress until every frozen target replica is done.
+
+Changing the target affects new uploads. Changing the minimum also re-evaluates retained cache for current uploads. Increasing the minimum does not move versions that are already stored back to an earlier state and cannot restore cache that has already been deleted.
+
 ## What Users See
 
 - S3 upload can succeed before Filecoin storage finishes.
 - Dashboard task and topology views show storage progress.
 - Reads prefer local cache. If remote metadata exists, SynapS3 can retrieve the object from the provider.
-- Cache eviction is an operational optimization, not the write acceptance point. `after_upload` removes a version after storage completes, `lru` waits for capacity pressure, and `none` retains it.
+- Cache eviction is an operational optimization, not the write acceptance point. `after_upload` removes a version after its minimum durable replicas are ready, `lru` waits for capacity pressure, and `none` retains it.
 
 ## Planned Replica Repair
 

docs/en/concepts/write-path-cache.md

@@ -39,10 +39,12 @@ Repeated reads of the same version coalesce access-time updates to at most one d
 | Policy | Behavior |
 | --- | --- |
 | `lru` | At the high capacity watermark, queue the least recently accessed remotely safe versions until planned usage reaches the low watermark. |
-| `after_upload` | Queue each version for removal after all target remote copies commit. |
+| `after_upload` | Queue each version for removal after its bucket's minimum durable copies commit. |
 | `none` | Do not create or run automatic cache eviction work. |
 
-Only versions with a readable committed remote copy are eligible. Eviction waits for active reads of the same version to close. Because cleanup is asynchronous, writes can still return `507 Insufficient Storage` when cleanup cannot keep pace or no safe candidate exists.
+Each bucket defaults to strict cache release, so the minimum equals the target replicas frozen for each upload. In the dashboard, set this on the bucket under Settings → Replica policy. An operator can set an explicit count from 1 through the current target. That count stays if Replicas later increases. Lowering Replicas below the stored count is rejected until Release cache after is also lowered. Lowering the threshold makes retained cache eligible for removal while remaining replicas continue syncing. Actual removal still follows `after_upload`, `lru`, or `none`. The minimum is clamped to each upload's target. Raising it affects cache that still exists; it cannot recreate cache that has already been deleted.
+
+Only versions that currently meet their minimum and have a readable committed remote copy are eligible. Eviction checks the current minimum again before authorizing deletion and waits for active reads of the same version to close. Because cleanup is asynchronous, writes can still return `507 Insufficient Storage` when cleanup cannot keep pace or no safe candidate exists.
 
 ## Multipart Uploads
 

docs/en/configuration/model.md

@@ -121,7 +121,7 @@ The login page uses a browser-session cookie by default. Selecting **Keep me sig
 Cache eviction policies have these user-visible results:
 
 - `lru`: when cache usage reaches the high watermark, SynapS3 removes the least recently accessed remotely safe entries until usage reaches the low watermark.
-- `after_upload`: after all target remote copies commit, SynapS3 queues that version for removal at the next Evictor poll. A later remote read can restore the cache, and that restored entry is not immediately removed again.
+- `after_upload`: after a version meets its bucket's minimum durable copies, SynapS3 queues it for removal at the next Evictor poll. A later remote read can restore the cache, and that restored entry is not immediately removed again.
 - `none`: SynapS3 does not automatically remove local cache data.
 
 The LRU watermarks must always satisfy `0 <= low < high <= 100`. They remain saved but have no effect under `after_upload` or `none`.

docs/en/operations/troubleshooting.md

@@ -109,10 +109,10 @@ Recovery options:
 - Confirm the host has free disk space, then increase `cache.max_size_gb` if capacity allows.
 - Restore storage provider connectivity and background task progress so queued uploads can complete and cache eviction can run.
 - Use the default `lru` policy for capacity-based cleanup. Lower the high watermark to leave more write headroom, and keep `0 <= low < high <= 100`.
-- Use `after_upload` only when each version should be removed on the next Evictor poll after all target remote copies commit.
+- Use `after_upload` only when each version should be removed on the next Evictor poll after its bucket's minimum durable copies commit.
 - Use `none` when automatic removal must be disabled.
 
-LRU cannot remove multipart staging data, versions that are not remotely durable, or versions without a readable committed remote copy. A write does not synchronously run eviction, so `507 Insufficient Storage` can continue until the Evictor catches up or safe candidates become available.
+LRU cannot remove multipart staging data, versions below their bucket's minimum durable copies, or versions without a readable committed remote copy. A write does not synchronously run eviction, so `507 Insufficient Storage` can continue until the Evictor catches up or safe candidates become available.
 
 Failed LRU deletion tasks remain visible as exhausted work and become eligible again after a one-hour cooldown. Fix the reported filesystem or database problem first; use `synaps3 admin task retry <id>` to retry sooner.
 

docs/en/reference/admin-api.md

@@ -114,7 +114,7 @@ Treat these endpoints as change-window operations. They can change data, credent
 | `POST` | `/api/v1/buckets` | Create a bucket. |
 | `GET` | `/api/v1/buckets/{name}` | Read bucket detail. |
 | `PUT` | `/api/v1/buckets/{name}/owner` | Update bucket owner. |
-| `PUT` | `/api/v1/buckets/{name}/copy-policy` | Update default copy policy. |
+| `PUT` | `/api/v1/buckets/{name}/copy-policy` | Update target replicas and/or the cache-release threshold. |
 | `DELETE` | `/api/v1/buckets/{name}` | Not supported. Returns `501 Not Implemented`. |
 | `GET` | `/api/v1/buckets/{name}/objects` | List objects. |
 | `DELETE` | `/api/v1/buckets/{name}/objects` | Create an object delete marker. |
@@ -133,6 +133,17 @@ Treat these endpoints as change-window operations. They can change data, credent
 
 For object upload, the HTTP `Content-Type` is the uploaded object's content type. It is not a JSON request marker.
 
+### Bucket Copy Policy
+
+`POST /api/v1/buckets` accepts optional `default_copies` and `minimum_durable_copies` fields. Bucket list, detail, create, and policy-update responses include:
+
+- `minimum_durable_copies`: the explicit bucket value, or `null` for strict per-upload behavior;
+- `effective_minimum_durable_copies`: the current display value after clamping the bucket minimum to the current target.
+
+`PUT /api/v1/buckets/{name}/copy-policy` accepts `default_copies` and `minimum_durable_copies` independently. An omitted field is unchanged. `default_copies: null` inherits the current runtime target for new uploads. `minimum_durable_copies: null` requires every replica frozen for each upload before releasing its cache. An explicit minimum must be between `1` and `8` and cannot exceed the target produced by the same request. An empty request or an invalid final combination returns `400 Bad Request`.
+
+Target changes affect new uploads. Minimum changes also re-evaluate retained cache for current uploads. Increasing the minimum cannot restore cache that has already been deleted.
+
 ### Permanently Delete Object Versions
 
 `POST /api/v1/buckets/{name}/objects/permanent-delete` accepts `key` and `version_id`. `POST /api/v1/buckets/{name}/objects/deleted/permanent-delete` accepts `key` and `delete_marker_version_id`.
@@ -222,6 +233,8 @@ The restore streams synchronously for up to one hour and requires enough cache c
 
 Cache settings expose `eviction_policy`, `lru_high_watermark_percent`, and `lru_low_watermark_percent` under `cache`. Valid policies are `lru`, `after_upload`, and `none`. Watermarks must satisfy `0 <= low < high <= 100` and only affect `lru`.
 
+When the full runtime is available, `GET /api/v1/settings` also returns `runtime_filecoin_default_copies`. This is the value used by the current process. `config.filecoin.default_copies` remains the saved value that takes effect after the next restart.
+
 After saving settings, restart SynapS3, check `/healthz`, and read settings again to confirm the effective values.
 
 ## Write Example

docs/zh/concepts/architecture.md

@@ -36,7 +36,7 @@ flowchart LR
 
 - 已确认的 S3 写入必须能承受异步上传失败。
 - 对象可见性和对象存储进度分开判断。
-- 只有配置的远端副本策略满足后，才执行缓存淘汰。
+- 只有达到存储桶的缓存释放门槛后，才执行缓存淘汰。默认门槛是每次上传冻结的目标副本数。
 - 设计优先单机，不依赖分布式协调。
 
 ## 对运维的影响

docs/zh/concepts/filecoin-storage-flow.md

@@ -30,8 +30,8 @@ flowchart TD
 | `cached` | 对象已在本地持久化，并排队等待上传。 |
 | `uploading` | 后台任务正在准备远端存储或上传对象数据。 |
 | `committing` | 存储提供方已有 piece，commit 步骤正在进行。 |
-| `replicating` | 至少已有一个可读副本，目标副本数仍在补齐。 |
-| `stored` | 目标远端副本策略已满足，并且已有存储元数据。 |
+| `replicating` | 至少已有一个可读已提交副本，但尚未达到存储桶的最低耐久副本门槛。 |
+| `stored` | 存储桶要求的最低耐久副本已可读并提交；其余目标副本可能仍在补齐。 |
 | `failed` | 正在执行的生命周期步骤失败，可重试。 |
 | `cache_evicted` | 远端持久化后，本地缓存已清理。 |
 
@@ -54,12 +54,18 @@ synaps3 admin task retry 42
 
 如果已建立的存储提供方在首次副本尚未全部完成时暂时不可用，SynapS3 会继续使用其他已分配且可写的副本。未完成副本会等待且不消耗重试次数，并在原存储提供方恢复可达后自动继续；系统不会自动选择替代提供方。已完成存储的副本随后变为不可用时，其修复仍属于下面计划支持的副本修复功能。
 
+## 目标副本与最低耐久副本
+
+上传开始时会冻结目标副本数。默认情况下，**Release cache after** 为 **All replicas (strict)**：该次上传冻结的全部目标副本都必须可读并完成提交。存储桶也可以设置 1 到当前目标之间的显式数量。显式数量在目标随后提高时保持不变；如果把 Replicas 降到低于该数量，请求会被拒绝，必须同时降低 Release cache after。**All replicas (strict)** 会跟随每次上传冻结的目标。达到该门槛后，版本进入已存储状态，缓存按已配置的淘汰策略处理；其余副本会继续补齐，直到达到该次上传的目标副本数。在冻结的目标副本全部完成前，仪表盘会继续显示副本同步进度。
+
+修改目标副本数只影响新上传。修改最低耐久副本数也会重新评估当前上传仍保留的缓存。提高门槛不会让已经进入已存储状态的版本回退，也无法恢复已经删除的缓存。
+
 ## 用户能看到什么
 
 - S3 上传可以在 Filecoin 存储完成前成功。
 - 仪表盘的任务和拓扑视图会展示存储进度。
 - 读取优先使用本地缓存；已有远端元数据时，可以从存储提供方取回对象。
-- 缓存淘汰是运维优化，不是写入接受点。`after_upload` 会在存储完成后清理版本，`lru` 等待容量压力，`none` 则保留本地缓存。
+- 缓存淘汰是运维优化，不是写入接受点。`after_upload` 会在最低耐久副本就绪后清理版本，`lru` 等待容量压力，`none` 则保留本地缓存。
 
 ## 计划支持的副本修复
 

docs/zh/concepts/write-path-cache.md

@@ -39,10 +39,12 @@ SynapS3 会校验请求，保存对象及其元数据，再返回 S3 兼容的 E
 | 策略 | 行为 |
 | --- | --- |
 | `lru` | 达到容量高水位后，按最近访问时间为远端安全的版本排队，直到计划使用量降至低水位。 |
-| `after_upload` | 所有目标远端副本提交后，为该版本排队清理。 |
+| `after_upload` | 存储桶要求的最低耐久副本提交后，为该版本排队清理。 |
 | `none` | 不创建或执行自动缓存淘汰任务。 |
 
-只有存在可读已提交远端副本的版本才可淘汰。淘汰会等待同一版本正在进行的读取关闭。清理是异步流程，因此清理追赶不及时或没有安全候选时，写入仍可能返回 `507 Insufficient Storage`。
+每个存储桶默认采用严格缓存释放策略，因此最低耐久副本数等于每次上传冻结的目标副本数。在仪表盘中，到该存储桶的 Settings → Replica policy 设置。运维人员可以设置 1 到当前目标之间的显式数量；目标随后提高时该数字保持不变。如果把 Replicas 降到低于已保存的显式数量，请求会被拒绝，必须同时降低 Release cache after。降低门槛只会让仍保留的缓存有资格被删除，其余副本会继续补齐。是否真正删除仍取决于 `after_upload`、`lru` 或 `none`。该门槛不会超过单次上传的目标副本数。提高门槛只影响尚未删除的缓存，无法恢复已经删除的缓存。
+
+只有当前满足最低耐久副本数且存在可读已提交远端副本的版本才可淘汰。系统会在授权删除前再次检查当前门槛，并等待同一版本正在进行的读取关闭。清理是异步流程，因此清理追赶不及时或没有安全候选时，写入仍可能返回 `507 Insufficient Storage`。
 
 ## 分段上传
 

docs/zh/configuration/model.md

@@ -121,7 +121,7 @@ SQLite 是 SynapS3 单机部署的默认且推荐数据库。已有 PostgreSQL 
 缓存淘汰策略会产生以下用户可见结果：
 
 - `lru`：缓存使用量达到高水位后，SynapS3 按最近访问时间淘汰最久未使用且远端安全的条目，直到降至低水位。
-- `after_upload`：所有目标远端副本提交后，该版本会在下一次 Evictor 轮询时加入清理。之后从远端读取并回填的缓存不会再次被立即删除。
+- `after_upload`：版本达到其存储桶要求的最低耐久副本数后，会在下一次 Evictor 轮询时加入清理。之后从远端读取并回填的缓存不会再次被立即删除。
 - `none`：SynapS3 不会自动清理本地缓存。
 
 LRU 水位始终必须满足 `0 <= low < high <= 100`。在 `after_upload` 或 `none` 下仍会保存这些值，但不会生效。

docs/zh/operations/troubleshooting.md

@@ -109,10 +109,10 @@ synaps3 admin settings get cache.lru_low_watermark_percent
 - 先确认主机仍有可用磁盘空间，再按容量增大 `cache.max_size_gb`。
 - 恢复存储提供方连接和后台任务进度，让排队上传完成并触发缓存淘汰。
 - 默认的 `lru` 适合按容量自动清理。降低高水位可以为新写入保留更多余量，并始终满足 `0 <= low < high <= 100`。
-- 只有希望所有目标远端副本提交后，在下一次 Evictor 轮询中删除对应版本时，才使用 `after_upload`。
+- 只有希望版本达到存储桶要求的最低耐久副本数后，在下一次 Evictor 轮询中删除对应版本时，才使用 `after_upload`。
 - 需要完全禁用自动清理时使用 `none`。
 
-LRU 无法清理 multipart 暂存数据、尚未远端持久化的版本，或没有可读已提交远端副本的版本。写入不会同步触发淘汰，因此在 Evictor 追赶完成或出现安全候选前，仍可能继续返回 `507 Insufficient Storage`。
+LRU 无法清理 multipart 暂存数据、未达到存储桶最低耐久副本数的版本，或没有可读已提交远端副本的版本。写入不会同步触发淘汰，因此在 Evictor 追赶完成或出现安全候选前，仍可能继续返回 `507 Insufficient Storage`。
 
 LRU 删除失败后，任务仍会作为 exhausted 工作保留，并在一小时冷却后重新具备执行资格。先修复任务中报告的文件系统或数据库问题；需要提前重试时，运行 `synaps3 admin task retry <id>`。