# Batch 10 (OCSP Cache + JS Events) Design

**Date:** 2026-02-27  
**Scope:** Design-only plan for Batch 10 (`20` features, `38` tests) covering Go files `server/ocsp_responsecache.go` and `server/jetstream_events.go`.

## Context Snapshot

PortTracker snapshot from:

- `/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 10 --db porting.db`
- `/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db`
- `/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db`

Observed facts:

- Batch ID: `10`
- Name: `OCSP Cache + JS Events`
- Dependency: `Batch 9`
- Status: `pending`
- Features: `20` (all currently `deferred`)
- Tests: `38` (all currently `deferred`)
- Overall progress: `1924/6942 (27.7%)`

Feature mapping summary:

- JetStream advisory publish path: `1959 (Server.publishAdvisory)`
- OCSP cache config/parser: `2472`, `2501`
- Local cache behavior: `2484-2497`
- Server OCSP cache lifecycle wiring: `2498-2500`

Readiness reality from dependency analysis (`sqlite3` on `porting.db`):

- All Batch 10 features have `0` unresolved dependencies.
- Batch 10 tests are mixed:
  - `8` tests become implementable once Batch 10 features are done.
  - `30` tests still depend on external deferred features (not in Batch 10), so they cannot be honestly verified in this batch.

## Problem Statement

Batch 10 is a foundational OCSP cache batch with one JetStream advisory method. The main risk is false progress: implementing local cache APIs superficially or marking cross-module tests verified while upstream features remain deferred.

## Constraints and Success Criteria

Constraints:

- Execute after Batch 9 dependency.
- Follow .NET standards (`.NET 10`, nullable, xUnit 3 + Shouldly + NSubstitute).
- No fake-pass tests and no production stubs promoted to `verified`.
- Status updates must be evidence-backed and chunked (`<= 15` IDs per batch-update).

Success criteria:

- All 20 Batch 10 features implemented with Go-behavior parity and verification evidence.
- Batch 10 mapped tests split correctly into:
  - truly verified tests (only when unblocked and passing), and
  - deferred tests with concrete dependency/runtime reasons.
- Batch completion only attempted after gates pass.

## Approaches

### Approach A: Minimal API shims (fast status movement)

Implement signatures for local cache and parser methods with simplified behavior.

- Pros: quick throughput.
- Cons: high semantic drift from Go behavior (stats, revocation preservation, atomic save path, timer semantics).

### Approach B: Full-fidelity OCSP cache parity in one pass (all tests now)

Implement complete OCSP cache and attempt to force all 38 tests to pass in Batch 10.

- Pros: ambitious closure.
- Cons: invalid for this dependency graph because 30 tests still depend on external deferred features.

### Approach C (Recommended): Feature-complete cache + dependency-aware test closure

Port all Batch 10 features fully, then verify only tests that become unblocked; keep externally blocked tests deferred with explicit evidence.

- Pros: truthful status accounting, lower regression risk, auditable progress.
- Cons: leaves some Batch 10 tests deferred until upstream batches progress.

## Recommended Design

### 1. Production Code Architecture

Primary code paths:

- `dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspTypes.cs`
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs`
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`

Expected new code files:

- `dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspHandler.cs`
  - `NewOCSPResponseCacheConfig`
  - `ParseOCSPResponseCache`
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.OcspResponseCache.cs`
  - `InitOCSPResponseCache`
  - `StartOCSPResponseCache`
  - `StopOCSPResponseCache`
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.JetStreamEvents.cs`
  - `PublishAdvisory`

Design intent:

- Replace simple disk `LocalDirCache` behavior with true Go-equivalent local cache semantics:
  - in-memory cache map
  - atomic stats (`hits/misses/goods/revokes/unknowns`)
  - compression/decompression
  - `PreserveRevoked` delete behavior
  - load/save with dirty flag + periodic save timer
- Keep parser behavior strict and deterministic (invalid shape/type/cache kind => config error).
- Keep server lifecycle integration explicit in start/stop/init flows.

### 2. Test Design

Primary test files:

- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspResponseCacheTests.cs`
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.Impltests.cs` (mapped batch tests)

Expected new test files:

- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspResponseCacheParserTests.cs`
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/NatsServerOcspCacheTests.cs`
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/NatsServerJetStreamEventsTests.cs`

Test strategy:

- TDD at feature-group granularity:
  - write failing tests for cache stats/timer/save-load/parser/server wiring/advisory publish
  - implement minimal parity
  - pass focused tests before status promotion
- For mapped Batch 10 tests:
  - verify only those with no unresolved external dependencies after feature completion
  - keep the rest deferred with explicit blocker IDs and reasons

### 3. Execution Slicing

Feature groups (`<=20` each):

- **F1 (1):** `1959`
- **F2 (13):** `2472,2484,2485,2486,2487,2488,2489,2490,2491,2492,2493,2494,2495`
- **F3 (6):** `2496,2497,2498,2499,2500,2501`

Test groups:

- **T1 Candidate Verify (8):** `1537,1538,1607,1625,1682,2442,2807,2894`
- **T2 Keep Deferred Unless Upstream Unblocks (30):** remaining Batch 10 test IDs

### 4. Risks and Mitigations

1. Timer/save behavior can introduce flaky tests.
Mitigation: deterministic timer intervals in tests, explicit waits with bounded timeouts, and repeated focused test runs.

2. Parser mismatch vs Go error semantics.
Mitigation: dedicated parser test matrix for accepted/rejected input shapes and type conversions.

3. Pressure to close all 38 tests inside this batch.
Mitigation: strict dependency evidence; external blockers stay deferred, never replaced by placeholders.

## Design Decision

Proceed with **Approach C**: full feature parity for Batch 10 plus dependency-aware test closure. This gives real progress on OCSP cache and JS advisory wiring while preventing incorrect verified statuses for externally blocked tests.