@quantod/qq 1.1.5 → 1.1.7

package/dist/resources/guide.md

@@ -1,6 +1,6 @@
 # QQ — Complete Reference
 
-QQ is a persistent, crash-safe pipeline for multi-stage agentic workflows. It is a **state machine with concurrency guarantees**: stages are states, items move through them, and `claim → release` is an atomic transition only one agent can hold at a time. State survives session restarts and crashes.
+QQ is a persistent, crash-safe pipeline for multi-stage agentic workflows. It is a **state machine with concurrency guarantees**: stages are states, items move through them, and `claim → process → release` is the atomic unit of work — only one agent holds a claim at a time. State survives session restarts and crashes.
 
 Use QQ when work fans out: web crawling, bulk API enrichment, research pipelines (find → filter → enrich), batch transforms, any task where multiple items move through multiple stages, possibly with concurrent agents working in parallel.
 
@@ -33,7 +33,7 @@ Items have:
 make_pipeline        → create a pipeline, get its name, once per setup
 push (N times)       → load items into a stage
 claim                → atomically lock one item (returns seq + payload)
-  ... do work ...
+  ... process the claimed item ...
 release              → unlock item, move to next stage, append payload
 status               → monitor progress
 unstick              → recover stuck/lost items
@@ -41,7 +41,7 @@ unstick              → recover stuck/lost items
 
 **Orchestrator** creates the pipeline, pushes items, spawns subagents, monitors with `status`, calls `batch_read` to collect results, calls `unstick` after.
 
-**Subagent** claims one item, does its work, releases to the next stage, repeats until "no items to claim" — then stops and reports back.
+**Subagent** claims one item, processes it, releases to the next stage, repeats until "no items to claim" — then stops and reports back. Never process an item before claiming it: another agent could claim and modify it concurrently.
 
 ---
 
@@ -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 → process → 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, process 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 → process → 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.7",
   "description": "Persistent queue for multi-stage Claude agent pipelines",
   "license": "UNLICENSED",
   "engines": {

package/src/resources/guide.md

@@ -1,6 +1,6 @@
 # QQ — Complete Reference
 
-QQ is a persistent, crash-safe pipeline for multi-stage agentic workflows. It is a **state machine with concurrency guarantees**: stages are states, items move through them, and `claim → release` is an atomic transition only one agent can hold at a time. State survives session restarts and crashes.
+QQ is a persistent, crash-safe pipeline for multi-stage agentic workflows. It is a **state machine with concurrency guarantees**: stages are states, items move through them, and `claim → process → release` is the atomic unit of work — only one agent holds a claim at a time. State survives session restarts and crashes.
 
 Use QQ when work fans out: web crawling, bulk API enrichment, research pipelines (find → filter → enrich), batch transforms, any task where multiple items move through multiple stages, possibly with concurrent agents working in parallel.
 
@@ -33,7 +33,7 @@ Items have:
 make_pipeline        → create a pipeline, get its name, once per setup
 push (N times)       → load items into a stage
 claim                → atomically lock one item (returns seq + payload)
-  ... do work ...
+  ... process the claimed item ...
 release              → unlock item, move to next stage, append payload
 status               → monitor progress
 unstick              → recover stuck/lost items
@@ -41,7 +41,7 @@ unstick              → recover stuck/lost items
 
 **Orchestrator** creates the pipeline, pushes items, spawns subagents, monitors with `status`, calls `batch_read` to collect results, calls `unstick` after.
 
-**Subagent** claims one item, does its work, releases to the next stage, repeats until "no items to claim" — then stops and reports back.
+**Subagent** claims one item, processes it, releases to the next stage, repeats until "no items to claim" — then stops and reports back. Never process an item before claiming it: another agent could claim and modify it concurrently.
 
 ---
 
@@ -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 → process → 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, process 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 → process → release` over `append`/`replace` whenever workers may be active.
 
 Returns the same shape as `load_file` (`summary` + `items`), without the `deleteAfter` behaviour.