Release 0.34.0

.secure.staging/.gitignore

@@ -0,0 +1,8 @@
+# Ignore all files in this directory (secure credentials)
+*
+
+# Allow structure files only
+!.gitignore
+!.gitkeep
+
+# NOTE: .env file inside this directory is also ignored (contains API keys/tokens)

CHANGELOG.md

@@ -22,6 +22,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [0.34.0] - 2026-08-25
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
 ## [0.33.3] - 2026-08-22
 ### Added
 

CLAUDE.md

@@ -537,6 +537,83 @@ Works with remote Docker via SSH. Gracefully degrades on discovery failures.
 
 ---
 
+### 8. Using Claim Check for Event Retrieval (Sprint 24)
+
+**Pattern for retrieving persisted events from outside the routing slip.**
+
+Claim check provides temporary Redis-backed storage for events and blobs with automatic TTL expiration. Use when a service needs access to the source event context (ingress/egress metadata) but doesn't have it in the current message.
+
+**Key use case**: Progress messages (Sprint 22) - LLM sends updates but needs original event's platform/channel info.
+
+```typescript
+// In tool-gateway or any Bit with MCP access
+async function sendProgressUpdate(correlationId: string, message: string) {
+  // Retrieve source event from claim check (Sprint 24: returns StoredSnapshot)
+  const claimTool = this.registry.getTool('claim.event.retrieve');
+
+  if (claimTool && claimTool.execute) {
+    const result = await claimTool.execute(
+      { correlationId },
+      { sessionId, userRoles: [] }
+    );
+
+    if (result && !result.isError) {
+      // Sprint 24: Result includes versioning metadata + event
+      const snapshot = JSON.parse(result.content[0].text);
+      const sourceEvent = snapshot.event; // Extract event from StoredSnapshot
+
+      // Optional: Check snapshot metadata
+      this.logger.debug('Retrieved snapshot', {
+        kind: snapshot.kind,           // 'initial' | 'update' | 'final' | 'deadletter'
+        capturedAt: snapshot.capturedAt,
+        sourceService: snapshot.sourceService
+      });
+
+      // Use ingress/egress from source event
+      await this.next({
+        ...progressEvent,
+        ingress: sourceEvent.ingress,  // Original platform context
+        egress: sourceEvent.egress,     // Original routing destination
+        identity: sourceEvent.identity, // Original user
+      });
+    }
+  }
+}
+```
+
+**Storage**: Events auto-stored by claim-check service on `internal.persistence.snapshot.v1` (ALL snapshot kinds: initial, update, final, deadletter). Timestamp-based versioning handles out-of-order delivery. Default TTL: 300s (5 min).
+
+**Versioning**: Uses `capturedAt` timestamp to determine event version. Newer snapshots overwrite older ones. Stale snapshots rejected. See `documentation/guides/claim-check.md` for out-of-order scenarios.
+
+**MCP Tools** (platform-only, 6 total):
+- `claim.event.retrieve(correlationId)` - Retrieve StoredSnapshot (includes versioning metadata + full event)
+- `claim.event.status(correlationId)` - Get metadata without full event (lightweight)
+- `claim.event.exists(correlationId)` - Check existence (boolean)
+- `claim.blob.store(data, contentType, ttl)` - Store binary data
+- `claim.blob.retrieve(blobId)` - Retrieve binary data
+- `claim.blob.exists(blobId)` - Check blob existence
+
+**Fail-open design**: If Redis unavailable or event expired, gracefully degrades (logs warning, continues execution).
+
+**Configuration**:
+```yaml
+# architecture.yaml
+claim-check:
+  profile: core
+  stage: persist
+  topics:
+    consumes:
+      - internal.persistence.snapshot.v1
+  env:
+    - CLAIM_CHECK_DEFAULT_TTL_SECONDS  # Default: 300
+    - CLAIM_CHECK_MAX_TTL_SECONDS      # Default: 3600
+    - REDIS_URL
+```
+
+**Documentation**: `documentation/guides/claim-check.md`
+
+---
+
 ### Quick Reference Patterns
 
 **Adding MCP Tool:**

architecture.yaml

@@ -4,7 +4,7 @@ description: >-
   Node/TypeScript, Twurple, Firestore, OpenAI. Deployed on Cloud Run.
 project:
   name: BitBrat Platform
-  version: 0.33.3
+  version: 0.34.0
   status: experimental
   description: >
     A cloud-native microservices suite that listens to Twitch, Kick and other events and provides tools to react to
@@ -595,6 +595,8 @@ services:
     topics:
       publishes:
         - internal.ingress.v1
+        # Sprint 24: Publishes 'initial' snapshots for unified persistence flow
+        # All ingested events immediately published as 'initial' snapshots after successful ingress
         - internal.persistence.snapshot.v1
       consumes:
         - internal.egress.v1.{instanceId}
@@ -752,8 +754,7 @@ services:
         - persistence
     topics:
       consumes:
-        - internal.ingress.v1
-        - internal.persistence.snapshot.v1
+        - internal.persistence.snapshot.v1  # Sprint 24: Snapshot-only persistence flow
         - internal.persistence.finalize.v1
         - internal.deadletter.v1
         - internal.router.dlq.v1
@@ -988,18 +989,44 @@ services:
     entry: src/apps/context-pack-service.ts
     port: 3000
   event-stream-analyzer:
-    profile: core  # Phase 1 POC uses stub analysis; will upgrade to 'llm' in Phase 2
+    profile: core
     category: platform
     mcp:
       exposure: platform-only
     active: true
-    description: 'Real-time event stream analysis using RxJS sliding windows (v4 streaming architecture)'
+    description: Real-time event stream analysis using RxJS sliding windows (v4 streaming architecture)
     kind: pipeline-service
     stage: analyze
     entry: src/apps/event-stream-analyzer-service.ts
     port: 3000
     secrets:
       - MCP_AUTH_TOKEN
+  claim-check:
+    category: platform
+    profile: core
+    mcp:
+      exposure: platform-only
+    active: true
+    description: Claim Check Bit - Temporary event and blob storage
+    kind: pipeline-service
+    stage: persist
+    stateful: false
+    entry: src/apps/claim-check-service.ts
+    port: 3008
+    dependencies:
+      infrastructure:
+        - messaging
+        - caching
+    topics:
+      consumes:
+        - internal.persistence.snapshot.v1
+      produces: []
+    env:
+      - CLAIM_CHECK_MAX_EVENT_SIZE_BYTES
+      - CLAIM_CHECK_MAX_BLOB_SIZE_BYTES
+      - CLAIM_CHECK_DEFAULT_TTL_SECONDS
+      - CLAIM_CHECK_MAX_TTL_SECONDS
+      - REDIS_URL
 executionContexts:
   local:
     description: Local Docker development environment