@quantod/qq 1.1.5 → 1.1.6

package/dist/resources/guide.md

@@ -327,6 +327,8 @@ Parameters:
 - `deleteAfter` (boolean, optional) — delete the file after loading. Default: true.
 - `duplicates` (`ignore` | `append` | `replace`, optional, default `ignore`) — how to handle records whose `id` already exists in the pipeline. `ignore`: skip silently (existing item unchanged). `append`: append the new record's payload to the existing item's payload and bump `seq` (invalidates any live claim). `replace`: replace the existing item's payload entirely and bump `seq`.
 
+**⚠ Avoid `append` and `replace` in production pipelines.** Both modes write to items outside the normal `claim → release` cycle, bypassing QQ's concurrency control. Any agent currently holding a claim on an affected item will find its `seq` token expired and lose its work. `replace` is especially destructive — it silently discards the existing payload with no recovery path. The correct way to update an item's payload is to `claim` it and `release` it with new content. Use `append`/`replace` only for offline data preparation before a pipeline has active workers.
+
 **Record format** (all fields optional):
 ```yaml
 id: item-1
@@ -367,7 +369,7 @@ Parameters:
 - `format` (`jsonl` | `json` | `yaml` | `csv`) — data format (explicit, no file extension to infer from)
 - `pipeline` (string)
 - `stage` (string, optional) — default stage. Defaults to empty string.
-- `duplicates` (`ignore` | `append` | `replace`, optional, default `ignore`) — same semantics as `load_file`
+- `duplicates` (`ignore` | `append` | `replace`, optional, default `ignore`) — same semantics as `load_file`. The same warning applies: prefer `claim → release` over `append`/`replace` whenever workers may be active.
 
 Returns the same shape as `load_file` (`summary` + `items`), without the `deleteAfter` behaviour.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantod/qq",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Persistent queue for multi-stage Claude agent pipelines",
   "license": "UNLICENSED",
   "engines": {

package/src/resources/guide.md

@@ -327,6 +327,8 @@ Parameters:
 - `deleteAfter` (boolean, optional) — delete the file after loading. Default: true.
 - `duplicates` (`ignore` | `append` | `replace`, optional, default `ignore`) — how to handle records whose `id` already exists in the pipeline. `ignore`: skip silently (existing item unchanged). `append`: append the new record's payload to the existing item's payload and bump `seq` (invalidates any live claim). `replace`: replace the existing item's payload entirely and bump `seq`.
 
+**⚠ Avoid `append` and `replace` in production pipelines.** Both modes write to items outside the normal `claim → release` cycle, bypassing QQ's concurrency control. Any agent currently holding a claim on an affected item will find its `seq` token expired and lose its work. `replace` is especially destructive — it silently discards the existing payload with no recovery path. The correct way to update an item's payload is to `claim` it and `release` it with new content. Use `append`/`replace` only for offline data preparation before a pipeline has active workers.
+
 **Record format** (all fields optional):
 ```yaml
 id: item-1
@@ -367,7 +369,7 @@ Parameters:
 - `format` (`jsonl` | `json` | `yaml` | `csv`) — data format (explicit, no file extension to infer from)
 - `pipeline` (string)
 - `stage` (string, optional) — default stage. Defaults to empty string.
-- `duplicates` (`ignore` | `append` | `replace`, optional, default `ignore`) — same semantics as `load_file`
+- `duplicates` (`ignore` | `append` | `replace`, optional, default `ignore`) — same semantics as `load_file`. The same warning applies: prefer `claim → release` over `append`/`replace` whenever workers may be active.
 
 Returns the same shape as `load_file` (`summary` + `items`), without the `deleteAfter` behaviour.