chore(release): 🔖 v0.13.0 (#224)

## Summary

Lockstep version bump to 0.13.0 for the Redis Streams event sink release
(#222, #223). Includes documentation updates, SDK/executor rebuild,
changelog promotion, and golden fixture updates.

## Highlights

- Bump `quarry/types/version.go`, `sdk/package.json`,
`sdk/src/types/events.ts` to 0.13.0
- Rebuild SDK dist and executor bundle with new version
- Promote CHANGELOG.md `[Unreleased]` → `[0.13.0] - 2026-03-12`
- Update golden test fixtures with `contract_version` 0.13.0
- Update `PUBLIC_API.md` version references from 0.12.2 → 0.13.0
- Add event sink documentation to configuration guide and integration
guide

## Test plan

- [ ] CI passes (Go tests, SDK tests, typecheck, lint, biome)
- [ ] Golden fixture contract versions match 0.13.0
- [ ] `quarry/types/version.go` = `sdk/package.json` =
`CONTRACT_VERSION` = 0.13.0
- [ ] CHANGELOG.md has dated `[0.13.0]` section with link reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: justapithecus

CHANGELOG.md

@@ -11,6 +11,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.13.0] - 2026-03-12
+
+### Added
+
+- **Integration**: Pluggable Redis Streams event sink — publishes every event in real time via `XADD` during run execution, enabling downstream consumers to watch events across all runs on a single stream (#222, #223)
+- **CLI**: `--event-sink` repeatable flag to activate event sinks (`lode`, `redis`); multiple sinks fan out with independent delivery semantics (#223)
+- **CLI**: Redis Streams event sink flags: `--event-sink-redis-url`, `--event-sink-redis-stream-key`, `--event-sink-redis-max-len`, `--event-sink-redis-ttl`, `--event-sink-redis-timeout`, `--event-sink-redis-retries`, `--event-sink-redis-delivery` (#223)
+- **Runtime**: Fan-out event sink with per-sink delivery classification — `mandatory` sinks fail the run on error; `best_effort` sinks log warnings and continue (#223)
+- **Contracts**: CONTRACT_INTEGRATION.md updated with Event Sink Model (scope, delivery semantics, failure behavior, fan-out inheritance) (#223)
+- **Contracts**: CONTRACT_CLI.md updated with event sink flag specifications (#223)
+- **Docs**: Integration guide updated with Redis Streams event sink section, comparison table, and YAML config example (#223)
+- **Docs**: Configuration guide updated with event sink flags and YAML schema (#223)
+
+### Changed
+
+- **Docs**: PUBLIC_API.md updated with event sink flags and downstream integration references (#223)
+
+---
+
 ## [0.12.2] - 2026-03-11
 
 ### Changed
@@ -510,7 +529,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/pithecene-io/quarry/compare/v0.12.2...HEAD
+[Unreleased]: https://github.com/pithecene-io/quarry/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/pithecene-io/quarry/compare/v0.12.2...v0.13.0
 [0.12.2]: https://github.com/pithecene-io/quarry/releases/tag/v0.12.2
 [0.12.1]: https://github.com/pithecene-io/quarry/releases/tag/v0.12.1
 [0.12.0]: https://github.com/pithecene-io/quarry/releases/tag/v0.12.0

PUBLIC_API.md

@@ -26,24 +26,24 @@ Quarry is **TypeScript-first** and **ESM-only**.
 ### Via mise (recommended)
 
 ```bash
-mise install github:pithecene-io/quarry@0.12.2
+mise install github:pithecene-io/quarry@0.13.0
 ```
 
 Or pin in your `mise.toml`:
 
 ```toml
 [tools]
-"github:pithecene-io/quarry" = "0.12.2"
+"github:pithecene-io/quarry" = "0.13.0"
 ```
 
 ### Via Docker
 
 ```bash
 # Full image — includes Chrome for Testing + fonts (amd64 only, recommended)
-docker pull ghcr.io/pithecene-io/quarry:0.12.2
+docker pull ghcr.io/pithecene-io/quarry:0.13.0
 
 # Slim image — no browser, multi-arch (BYO Chromium via --browser-ws-endpoint)
-docker pull ghcr.io/pithecene-io/quarry:0.12.2-slim
+docker pull ghcr.io/pithecene-io/quarry:0.13.0-slim
 ```
 
 See [docs/guides/container.md](docs/guides/container.md) for `docker run` and Docker Compose examples.
@@ -468,6 +468,25 @@ CLI flags always override config file values.
 | `--adapter-timeout <duration>` | `10s` | Notification timeout |
 | `--adapter-retries <n>` | `3` | Retry attempts |
 
+**Event sink flags (real-time event delivery, v0.13.0+):**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--event-sink <type>` | | Event sink type (`lode`, `redis`); repeatable |
+| `--event-sink-lode-delivery` | `mandatory` | Delivery mode for Lode event sink |
+| `--event-sink-redis-url <url>` | | Redis URL (required when `--event-sink` includes `redis`) |
+| `--event-sink-redis-stream-key` | `quarry:events` | Redis Streams key |
+| `--event-sink-redis-max-len` | `100000` | Max stream length (-1 disables) |
+| `--event-sink-redis-ttl` | `24h` | Stream key expiry (-1 disables) |
+| `--event-sink-redis-timeout` | `2s` | Per-operation timeout |
+| `--event-sink-redis-retries` | `2` | Retry attempts |
+| `--event-sink-redis-delivery` | `mandatory` | Delivery mode for Redis event sink |
+
+> **Event sinks vs adapters:** Event sinks deliver events in real time during a
+> run. Adapters fire once after a run completes. Both can be used together.
+> When no `--event-sink` flags are set, events go to Lode only (default).
+> See `docs/contracts/CONTRACT_INTEGRATION.md` and `docs/guides/integration.md`.
+
 **Fan-out flags (derived work execution):**
 
 | Flag | Default | Description |
@@ -726,22 +745,22 @@ executor runs under Node ESM.
 
 Quarry ships container images via GHCR:
 
-- **Full** (amd64 only): `ghcr.io/pithecene-io/quarry:0.12.2` — includes Chrome for Testing + fonts
-- **Slim** (amd64 + arm64): `ghcr.io/pithecene-io/quarry:0.12.2-slim` — no browser (BYO via `--browser-ws-endpoint`)
+- **Full** (amd64 only): `ghcr.io/pithecene-io/quarry:0.13.0` — includes Chrome for Testing + fonts
+- **Slim** (amd64 + arm64): `ghcr.io/pithecene-io/quarry:0.13.0-slim` — no browser (BYO via `--browser-ws-endpoint`)
 
 For `docker run`, Docker Compose, and sidecar patterns, see [docs/guides/container.md](docs/guides/container.md).
 
 ---
 
-## Known Limitations (v0.12.2)
+## Known Limitations (v0.13.0)
 
 1. **Single executor type**: Only Node.js executor supported
 2. **No built-in retries**: Retry logic is caller's responsibility
 3. **No streaming reads**: Artifacts must fit in memory (note: the `streaming` *ingestion policy* is unrelated — it controls write batching, not read access)
 4. **No transactional storage writes**: S3 and S3-compatible providers (R2, MinIO) do not provide transactional guarantees across writes
 5. **No job scheduling**: Quarry supports in-process derived work via `--depth` but is not a scheduler; external orchestration is the caller's responsibility
 6. **Puppeteer required**: All scripts run in a browser context
-7. **Event bus adapters**: Webhook and Redis pub/sub adapters are available. Temporal, NATS, and SNS adapters are planned. See `docs/guides/integration.md`.
+7. **Integration adapters and sinks**: Webhook, Redis Pub/Sub, and Redis Streams are available. Temporal, NATS, and SNS adapters are planned. Event sink read-side interfaces are tabled for future work. See `docs/guides/integration.md`.
 8. **Fan-out partition defaults**: Child runs inherit the root run's `--source` and `--category` unless overridden via `emit.enqueue({ source, category })`. Overrides apply to individual child runs only and do not propagate to grandchildren.
 9. **Fan-out target resolution**: `target` in `emit.enqueue()` is resolved as a file path relative to CWD (same as `--script`). Target resolution semantics may change in a future release; config-based logical names are under consideration.
 
@@ -810,6 +829,10 @@ processing after runs complete, see [docs/guides/integration.md](docs/guides/int
 `--adapter redis` publishes to a Redis pub/sub channel after each run completes.
 See adapter flags above.
 
+**Event sinks** (v0.13.0+): `--event-sink redis` streams every event to a Redis
+Stream in real time during the run. Can be combined with adapters for both
+real-time event streaming and post-run notification.
+
 **Fallback pattern**: Polling-based triggers with idempotent checkpoints.
 
 ---
@@ -818,7 +841,7 @@ See adapter flags above.
 
 ```bash
 quarry version
-# 0.12.2 (commit: ...)
+# 0.13.0 (commit: ...)
 ```
 
 SDK and runtime versions must match (lockstep versioning).
@@ -827,8 +850,8 @@ SDK and runtime versions must match (lockstep versioning).
 
 | Component | Channel | Install |
 |-----------|---------|---------|
-| CLI binary | GitHub Releases | `mise install github:pithecene-io/quarry@0.12.2` |
-| Container (full, amd64) | GHCR | `docker pull ghcr.io/pithecene-io/quarry:0.12.2` |
-| Container (slim, multi-arch) | GHCR | `docker pull ghcr.io/pithecene-io/quarry:0.12.2-slim` |
+| CLI binary | GitHub Releases | `mise install github:pithecene-io/quarry@0.13.0` |
+| Container (full, amd64) | GHCR | `docker pull ghcr.io/pithecene-io/quarry:0.13.0` |
+| Container (slim, multi-arch) | GHCR | `docker pull ghcr.io/pithecene-io/quarry:0.13.0-slim` |
 | SDK | JSR | `npx jsr add @pithecene-io/quarry-sdk` |
 | SDK | GitHub Packages | `pnpm add @pithecene-io/quarry-sdk` |

docs/CLI_PARITY.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "CLI flag/config parity artifact. Machine-checkable source of truth for CLI flags.",
   "commands": {
     "run": {

docs/guides/configuration.md

@@ -116,6 +116,26 @@ See `docs/guides/proxy.md` for pool configuration format and selection behavior.
 
 See `docs/guides/integration.md` for adapter usage patterns.
 
+### Event Sinks (Real-Time Event Delivery)
+
+| Flag | Type | Default | Purpose |
+|------|------|---------|---------|
+| `--event-sink` | string (repeatable) | | Event sink type (`lode`, `redis`) |
+| `--event-sink-lode-delivery` | string | `mandatory` | Delivery mode for Lode event sink |
+| `--event-sink-redis-url` | string | | Redis URL (required when `--event-sink` includes `redis`) |
+| `--event-sink-redis-stream-key` | string | `quarry:events` | Redis Streams key |
+| `--event-sink-redis-max-len` | int | `100000` | Max stream length (-1 disables trimming) |
+| `--event-sink-redis-ttl` | duration | `24h` | Stream key expiry (-1 disables) |
+| `--event-sink-redis-timeout` | duration | `2s` | Per-operation timeout |
+| `--event-sink-redis-retries` | int | `2` | Retry attempts |
+| `--event-sink-redis-delivery` | string | `mandatory` | Delivery mode for Redis event sink |
+
+Event sinks receive events in real time during a run (unlike adapters, which
+fire once after a run completes). When no `--event-sink` flags are set, events
+go to Lode only (default behavior). Each sink declares a delivery mode:
+`mandatory` (failure may fail the run) or `best_effort` (failure logged,
+run continues). See `docs/contracts/CONTRACT_INTEGRATION.md` for semantics.
+
 ### Fan-Out (Derived Work Execution)
 
 | Flag | Type | Default | Purpose |
@@ -328,6 +348,21 @@ adapter:
     Authorization: Bearer ${WEBHOOK_TOKEN}
   timeout: 10s
   retries: 3
+
+# Event sinks for real-time event delivery (v0.13.0+).
+# When absent, events go to Lode only (default behavior).
+# events:
+#   sinks:
+#     - type: lode
+#       delivery: mandatory
+#     - type: redis
+#       delivery: best_effort
+#       url: redis://localhost:6379
+#       stream_key: quarry:events
+#       max_len: 100000
+#       ttl: 24h
+#       timeout: 2s
+#       retries: 2
 ```
 
 ### Environment Variable Expansion

docs/guides/container.md

@@ -11,8 +11,8 @@ Quarry ships two container images via GHCR:
 
 | Image | Tag | Arch | Includes |
 |-------|-----|------|----------|
-| Full | `ghcr.io/pithecene-io/quarry:0.12.2` | amd64 | Quarry CLI, Node.js, Puppeteer, Chrome for Testing, fonts |
-| Slim | `ghcr.io/pithecene-io/quarry:0.12.2-slim` | amd64, arm64 | Quarry CLI, Node.js, Puppeteer (no browser) |
+| Full | `ghcr.io/pithecene-io/quarry:0.13.0` | amd64 | Quarry CLI, Node.js, Puppeteer, Chrome for Testing, fonts |
+| Slim | `ghcr.io/pithecene-io/quarry:0.13.0-slim` | amd64, arm64 | Quarry CLI, Node.js, Puppeteer (no browser) |
 
 The **full** image is recommended for standalone usage. The **slim** image is
 for environments where Chromium is provided externally (e.g., via
@@ -34,7 +34,7 @@ and run as a non-root `quarry` user.
 docker run --rm \
   -v ./scripts:/work/scripts:ro \
   -v ./data:/work/data \
-  ghcr.io/pithecene-io/quarry:0.12.2 \
+  ghcr.io/pithecene-io/quarry:0.13.0 \
   run \
     --script ./scripts/my-script.ts \
     --run-id "run-$(date +%s)" \
@@ -50,7 +50,7 @@ docker run --rm \
 ```yaml
 services:
   quarry:
-    image: ghcr.io/pithecene-io/quarry:0.12.2
+    image: ghcr.io/pithecene-io/quarry:0.13.0
     volumes:
       - ./scripts:/work/scripts:ro
       - ./data:/work/data
@@ -71,7 +71,7 @@ services:
 ```yaml
 services:
   quarry:
-    image: ghcr.io/pithecene-io/quarry:0.12.2
+    image: ghcr.io/pithecene-io/quarry:0.13.0
     volumes:
       - ./scripts:/work/scripts:ro
     environment:
@@ -99,7 +99,7 @@ services:
       - "6379:6379"
 
   quarry:
-    image: ghcr.io/pithecene-io/quarry:0.12.2
+    image: ghcr.io/pithecene-io/quarry:0.13.0
     depends_on:
       - redis
     volumes:
@@ -135,7 +135,7 @@ executor where to find them:
 ```yaml
 services:
   quarry:
-    image: ghcr.io/pithecene-io/quarry:0.12.2
+    image: ghcr.io/pithecene-io/quarry:0.13.0
     volumes:
       - ./scripts:/work/scripts:ro
       - ./node_modules:/work/node_modules:ro
@@ -167,7 +167,7 @@ services:
       - "9222:9222"
 
   quarry:
-    image: ghcr.io/pithecene-io/quarry:0.12.2-slim
+    image: ghcr.io/pithecene-io/quarry:0.13.0-slim
     depends_on:
       - chrome
     volumes:

docs/guides/integration.md

@@ -183,6 +183,69 @@ adapter:
   retries: 3
 ```
 
+### Redis Streams Event Sink (v0.13.0+)
+
+Unlike the adapters above, which fire once after a run completes, the Redis
+Streams **event sink** publishes every event in real time as the executor
+produces it. This enables downstream consumers to watch events across all
+runs on a single stream.
+
+```bash
+quarry run \
+  --script ./script.ts \
+  --run-id run-001 \
+  --source my-source \
+  --storage-backend fs \
+  --storage-path ./data \
+  --event-sink lode \
+  --event-sink redis \
+  --event-sink-redis-url redis://localhost:6379
+```
+
+Each event is published via `XADD` with flat fields: `run_id`, `event_type`,
+`seq`, `timestamp`, `source`, `category`, and `payload` (JSON-encoded).
+
+#### Event Sink vs Adapter
+
+| | Event Sink | Adapter |
+|---|---|---|
+| **Timing** | During run (real-time) | After run completes |
+| **Events** | Every event | Single `run_completed` summary |
+| **Failure** | Configurable (`mandatory` or `best_effort`) | Always best-effort |
+| **Transport** | Redis Streams (`XADD`) | Redis Pub/Sub (`PUBLISH`) or HTTP POST |
+| **Flags** | `--event-sink` | `--adapter` |
+
+Both can be used together in the same run.
+
+#### YAML Config Example
+
+```yaml
+events:
+  sinks:
+    - type: lode
+      delivery: mandatory
+    - type: redis
+      delivery: best_effort
+      url: redis://localhost:6379
+      stream_key: quarry:events
+      max_len: 100000
+      ttl: 24h
+```
+
+#### Event Sink Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--event-sink-redis-stream-key` | `quarry:events` | Shared stream key |
+| `--event-sink-redis-max-len` | `100000` | Approximate stream cap (-1 disables) |
+| `--event-sink-redis-ttl` | `24h` | Key expiry (-1 disables) |
+| `--event-sink-redis-timeout` | `2s` | Per-operation timeout |
+| `--event-sink-redis-retries` | `2` | Retry attempts with exponential backoff |
+| `--event-sink-redis-delivery` | `mandatory` | `mandatory` or `best_effort` |
+
+See `docs/contracts/CONTRACT_INTEGRATION.md` §Event Sink Model for full
+semantics.
+
 ### Interim Pattern (v0.4.x)
 
 Before v0.5.0, use a shell wrapper to trigger downstream notifications:

quarry/executor/bundle/executor.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Quarry Executor Bundle v0.12.2
+// Quarry Executor Bundle v0.13.0
 // This is a bundled version for embedding in the quarry binary.
 // Do not edit directly - regenerate with: task executor:bundle
 
@@ -332,7 +332,7 @@ var CONTRACT_VERSION, TerminalEventError, SinkFailedError, StorageFilenameError,
 var init_dist = __esm({
   "../sdk/dist/index.mjs"() {
     "use strict";
-    CONTRACT_VERSION = "0.12.2";
+    CONTRACT_VERSION = "0.13.0";
     TerminalEventError = class extends Error {
       constructor() {
         super("Cannot emit: a terminal event (run_error or run_complete) has already been emitted");

quarry/types/version.go

@@ -5,4 +5,4 @@ package types
 // per the lockstep versioning policy.
 //
 // This version is authoritative. Contract docs must reference this constant.
-const Version = "0.12.2"
+const Version = "0.13.0"

sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithecene-io/quarry-sdk",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://npm.pkg.github.com"

sdk/src/types/events.ts

@@ -2,7 +2,7 @@
  * Event envelope and payload types per CONTRACT_EMIT.md
  */
 
-export const CONTRACT_VERSION = '0.12.2' as const
+export const CONTRACT_VERSION = '0.13.0' as const
 export type ContractVersion = typeof CONTRACT_VERSION
 
 /** Branded type for run identifiers */