AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
backendcritical PriorityID: nats-jetstream-deterministic-deduplication-guardrail

Deterministic Deduplication and Optimistic Concurrency Invariants in NATS JetStream 2.11

Mandates deterministic Nats-Msg-Id generation and optimistic concurrency headers across all publisher operations in NATS JetStream 2.11. Eliminates phantom state drifts and dual-write anomalies across geo-distributed clusters by enforcing stream-level deduplication windows and aggregate sequence invariants instead of relying on distributed two-phase locking.

Prohibited Anti-Pattern: Publishing State-Altering Events with Ephemeral UUIDs and Missing Concurrency Control Headers

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Deterministic Deduplication and Optimistic Concurrency Invariants in NATS JetStream 2.11 - Mandates deterministic Nats-Msg-Id generation and optimistic concurrency headers across all publisher operations in NATS JetStream 2.11. Eliminates phantom state drifts and dual-write anomalies across geo-distributed clusters by enforcing stream-level deduplication windows and aggregate sequence invariants instead of relying on distributed two-phase locking.
globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, services/**/*.ts
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/nats-jetstream-deterministic-deduplication-guardrail"
---

# Deterministic Deduplication and Optimistic Concurrency Invariants in NATS JetStream 2.11

> **Severity**: CRITICAL | **Category**: backend
> **Anti-Pattern Warning**: Publishing State-Altering Events with Ephemeral UUIDs and Missing Concurrency Control Headers

## System Constraints
You are a Principal Engineer enforcing NATS JetStream 2.11 Deterministic Message Deduplication Invariant. Mandate invariants that prevent state machine divergence in geo-distributed topologies: publishers must use deterministic, content-derived Nats-Msg-Id headers, establish optimistic concurrency control via Nats-Expected-Last-Msg-Id or Nats-Expected-Last-Subject-Sequence, configure explicit stream duplicate_window constraints, and handle duplicate PubAcks gracefully.

## Strict Guidelines
- Engineers MUST ALWAYS generate 'Nats-Msg-Id' using a deterministic composite format derived from the domain aggregate ID and sequence/state version (e.g., `${aggregateType}:${aggregateId}:${sequenceNumber}`).
- Engineers MUST NOT use random UUIDs (such as crypto.randomUUID() or v4()) as the 'Nats-Msg-Id' for state-transition events, as retries will bypass the JetStream deduplication window.
- Publishers MUST set optimistic concurrency control headers ('Nats-Expected-Last-Msg-Id' or 'Nats-Expected-Last-Subject-Sequence') on state-mutating events to guarantee linearizable transitions without distributed database locks.
- Services MUST gracefully inspect 'PubAck.duplicate' upon publishing; if true, the operation must be treated as successful and idempotent rather than an exceptional error.
- Stream configuration MUST explicitly define 'duplicate_window' to match or exceed the maximum retry and reconciliation window of upstream producers.

## Bad vs Good Implementations
### JetStream Publishing with Deterministic Deduplication and Concurrency Checks

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Using crypto.randomUUID() generates a unique ID on every retry attempt, bypassing the JetStream deduplication engine and causing duplicate ledger entries. Omitting optimistic concurrency headers (Nats-Expected-Last-Msg-Id) allows network partitions or out-of-order retries to corrupt aggregate states.
```typescript
import { JetStreamClient, headers } from 'nats';
import { randomUUID } from 'node:crypto';

interface OrderPlacedEvent {
  orderId: string;
  version: number;
  amount: number;
}

export async function publishOrderEvent(js: JetStreamClient, event: OrderPlacedEvent): Promise<void> {
  const h = headers();
  // ANTI-PATTERN: Random UUID defeats JetStream deduplication during network retry
  h.set('Nats-Msg-Id', randomUUID());

  // ANTI-PATTERN: Missing optimistic concurrency checks allows out-of-order state overwrites
  const ack = await js.publish('orders.v1.placed', Buffer.from(JSON.stringify(event)), { headers: h });

  // ANTI-PATTERN: Fails to evaluate duplicate ack flag
  console.log(`Published sequence: ${ack.seq}`);
}
```

#### Production Standard (Correct)
> **Standard**: The good implementation constructs a deterministic 'Nats-Msg-Id' using domain invariants, guaranteeing that retries within the stream's duplicate_window are identified as identical messages. Enforcing 'Nats-Expected-Last-Msg-Id' establishes serializability without external distributed locks, and checking ack.duplicate ensures idempotent execution.
```typescript
import { JetStreamClient, headers, PubAck } from 'nats';

interface OrderPlacedEvent {
  orderId: string;
  version: number;
  previousVersionMsgId: string | null;
  amount: number;
}

export async function publishOrderEvent(js: JetStreamClient, event: OrderPlacedEvent): Promise<PubAck> {
  const h = headers();
  
  // INVARIANT: Deterministic message ID tied directly to aggregate boundary and version
  const deterministicMsgId = `order:${event.orderId}:v${event.version}`;
  h.set('Nats-Msg-Id', deterministicMsgId);

  // INVARIANT: Linearizable stream ordering via optimistic concurrency validation
  if (event.previousVersionMsgId) {
    h.set('Nats-Expected-Last-Msg-Id', event.previousVersionMsgId);
  } else {
    // Stream must not already contain messages for this new aggregate subject
    h.set('Nats-Expected-Last-Subject-Sequence', '0');
  }

  const subject = `orders.v1.${event.orderId}`;
  const payload = Buffer.from(JSON.stringify(event));

  const ack = await js.publish(subject, payload, { headers: h });

  // INVARIANT: Idempotent handling of duplicate publishes
  if (ack.duplicate) {
    // Log at debug level; state machine remains valid
    return ack;
  }

  return ack;
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

NATS JetStream MCP Server
Validates stream configurations, deduplication windows, and active subject sequence hierarchies.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

NATS Unified CLI
Administers JetStream streams, inspects duplicate_window metrics, and analyzes sequence divergence.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Deduplication and Optimistic Concurrency Invariants in NATS JetStream 2.11

Deterministic Deduplication and Optimistic Concurrency Invariants in NATS JetStream 2.11 defines an industrial-grade behavioral standard for backend engineering. Mandates deterministic Nats-Msg-Id generation and optimistic concurrency headers across all publisher operations in NATS JetStream 2.11. Eliminates phantom state drifts and dual-write anomalies across geo-distributed clusters by enforcing stream-level deduplication windows and aggregate sequence invariants instead of relying on distributed two-phase locking. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Publishing State-Altering Events with Ephemeral UUIDs and Missing Concurrency Control Headers Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftPublishing State-Altering Events with Ephemeral UUIDs and Missing Concurrency Control HeadersCritical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Engineers MUST ALWAYS generate 'Nats-Msg-Id' using a deterministic composite format derived from the domain aggregate ID and sequence/state version (e.g., `${aggregateType}

Engineers MUST ALWAYS generate 'Nats-Msg-Id' using a deterministic composite format derived from the domain aggregate ID and sequence/state version (e.g., `${aggregateType}:${aggregateId}:${sequenceNumber}`).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT use random UUIDs (such as crypto.randomUUID() or v4()) as the 'Nats-Msg-Id' for state-transition events, as retries will bypass the JetStream deduplication window.

Engineers MUST NOT use random UUIDs (such as crypto.randomUUID() or v4()) as the 'Nats-Msg-Id' for state-transition events, as retries will bypass the JetStream deduplication window.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Publishers MUST set optimistic concurrency control headers ('Nats-Expected-Last-Msg-Id' or 'Nats-Expected-Last-Subject-Sequence') on state-mutating events to guarantee linearizable transitions without distributed database locks.

Publishers MUST set optimistic concurrency control headers ('Nats-Expected-Last-Msg-Id' or 'Nats-Expected-Last-Subject-Sequence') on state-mutating events to guarantee linearizable transitions without distributed database locks.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Services MUST gracefully inspect 'PubAck.duplicate' upon publishing

Services MUST gracefully inspect 'PubAck.duplicate' upon publishing; if true, the operation must be treated as successful and idempotent rather than an exceptional error.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Stream configuration MUST explicitly define 'duplicate_window' to match or exceed the maximum retry and reconciliation window of upstream producers.

Stream configuration MUST explicitly define 'duplicate_window' to match or exceed the maximum retry and reconciliation window of upstream producers.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Deterministic Deduplication and Optimistic Concurrency Invariants in NATS JetStream 2.11 critical for AI coding assistants?

Mandates deterministic Nats-Msg-Id generation and optimistic concurrency headers across all publisher operations in NATS JetStream 2.11. Eliminates phantom state drifts and dual-write anomalies across geo-distributed clusters by enforcing stream-level deduplication windows and aggregate sequence invariants instead of relying on distributed two-phase locking. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Publishing State-Altering Events with Ephemeral UUIDs and Missing Concurrency Control Headers) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related BACKEND Rules

View all rules →
backend
42

Fastify 5 Schema Compilers & Encapsulation Production Standard

Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree.

backend
68

Bun Embedded SQLite WAL Mode & Transaction Synchronization Standard

Production database standard for bun:sqlite. Mandates enabling Write-Ahead Logging (PRAGMA journal_mode = WAL), busy timeouts, and using db.transaction() for atomic operations without lock starvation.

backend
68

Drizzle ORM Batch API & Interactive Transaction Isolation Standard

Production database standard for Drizzle ORM (PostgreSQL & MySQL). Mandates using db.batch() over HTTP drivers to prevent round-trip waterfalls, explicit db.transaction() with serializable/read-committed isolation, and strictly avoids unawaited query promises.

1 Rule in Stack

Deterministic