Files

Joseph Doherty b928be4f2f Add batch plans for batches 1-5 and 8 (rounds 1-3)

Generated design docs and implementation plans via Codex for:
- Batch 1: Proto, Const, CipherSuites, NKey, JWT
- Batch 2: Parser, Sublist, MemStore remainders
- Batch 3: SendQ, Service, Client ProxyProto
- Batch 4: Logging
- Batch 5: JetStream Errors
- Batch 8: Store Interfaces

All plans include mandatory verification protocol and anti-stub guardrails.
Updated batches.md with file paths and planned status.

2026-02-27 14:11:29 -05:00

17 KiB

Raw Blame History

Batch 5 (JetStream Errors) Implementation Plan

For Codex: REQUIRED SUB-SKILL: Use executeplan to implement this plan task-by-task.

Goal: Implement and verify Batch 5 JetStream error helper parity (206 features) and resolve the 11 mapped tests with evidence-backed status updates.

Architecture: Keep canonical JsApiError constants in hand-authored code, add missing helper parity (ParseOpts, ToReplacerArgs), and generate constructor surface for all missing NewJS*Error methods in grouped increments (<=20 features). Use strict verification gates after each group: stub scan, build, focused tests, and status updates in <=15-ID chunks with captured evidence.

Tech Stack: .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (porting.db)

Design doc: docs/plans/2026-02-27-batch-5-jetstream-errors-design.md

Batch 5 Working Set

Batch facts:

Batch ID: 5
Features: 206 (all currently deferred)
Tests: 11 (all currently deferred)
Dependencies: none
Go sources: server/jetstream_errors.go, server/jetstream_errors_generated.go

Feature groups (<=20 features each):

Group 01 (20): 1751,1752,1755,1756,1757,1758,1759,1760,1761,1762,1763,1764,1765,1766,1767,1768,1769,1770,1771,1772
Group 02 (20): 1773,1774,1775,1776,1777,1778,1779,1780,1781,1782,1783,1784,1785,1786,1787,1788,1789,1790,1791,1792
Group 03 (20): 1793,1794,1795,1796,1797,1798,1799,1800,1801,1802,1803,1804,1805,1806,1807,1808,1809,1810,1811,1812
Group 04 (20): 1813,1814,1815,1816,1817,1818,1819,1820,1821,1822,1823,1824,1825,1826,1827,1828,1829,1830,1831,1832
Group 05 (20): 1833,1834,1835,1836,1837,1838,1839,1840,1841,1842,1843,1844,1845,1846,1847,1848,1849,1850,1851,1852
Group 06 (20): 1853,1854,1855,1856,1857,1858,1859,1860,1861,1862,1863,1864,1865,1866,1867,1868,1869,1870,1871,1872
Group 07 (20): 1873,1874,1875,1876,1877,1878,1879,1880,1881,1882,1883,1884,1885,1886,1887,1888,1889,1890,1891,1892
Group 08 (20): 1893,1894,1895,1896,1897,1898,1899,1900,1901,1902,1903,1904,1905,1906,1907,1908,1909,1910,1911,1912
Group 09 (20): 1913,1914,1915,1916,1917,1918,1919,1920,1921,1922,1923,1924,1925,1926,1927,1928,1929,1930,1931,1932
Group 10 (20): 1933,1934,1935,1936,1937,1938,1939,1940,1941,1942,1943,1944,1945,1946,1947,1948,1949,1950,1951,1952
Group 11 (6): 1953,1954,1955,1956,1957,1958

Mapped tests in this batch:

742, 1304, 1476, 1606, 1694, 1696, 1708, 1757, 1767, 1777, 2272

Batch-5-linked features referenced by those tests:

1765, 1806, 1821, 1876, 1883, 1903, 1916, 1930, 1938, 1953

MANDATORY VERIFICATION PROTOCOL

NON-NEGOTIABLE: this protocol applies to every feature group and every test task.

Per-Feature Verification Loop (REQUIRED for every feature ID)

Read the mapped Go source (feature show <id> + source file/line).
Implement or update mapped C# method in the mapped class.
Run focused constructor/helper tests for that feature group.
Run build gate.
Run related test gate.
Only then add the feature ID to complete/verified candidate lists.

Focused run pattern:

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~JetStreamErrorsGeneratedConstructorsTests.ConstructorSurface_Group<NN>" \
  --verbosity normal

Stub Detection Check (REQUIRED after every feature group and test class)

Run on touched files only:

rg -n "NotImplementedException|throw new NotSupportedException\(|TODO|PLACEHOLDER" \
  dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamErrors*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/*.cs

rg -n "Assert\.True\(true\)|Assert\.Pass\(|\.ShouldBe\(true\);$|^\s*\{\s*\}$" \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/*.cs

Any hit in edited code blocks status promotion until resolved or explicitly deferred.

Build Gate (REQUIRED after each feature group)

dotnet build dotnet/

Required: zero errors.

Test Gate (REQUIRED before marking any feature `verified`)

Run all related classes and require Failed: 0:

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~JetStreamErrorsTests|FullyQualifiedName~JetStreamErrorsGeneratedConstructorsTests" \
  --verbosity normal

For the 10 features linked to tracked tests (1765,1806,1821,1876,1883,1903,1916,1930,1938,1953), related mapped test IDs must also pass before those features can move to verified. If those tests are infra-blocked, keep those features at complete and document blocker.

Status Update Protocol (REQUIRED)

Maximum 15 IDs per feature batch-update or test batch-update command.
Evidence is required for every status update chunk:
- focused test pass output
- build gate output
- related test gate output
- stub scan output
State progression:
- Features: deferred -> stub -> complete -> verified
- Tests: deferred -> stub -> verified (or stay deferred with explicit reason)

Command templates:

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "<max15ids>" --set-status stub --db porting.db --execute

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "<max15ids>" --set-status complete --db porting.db --execute

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "<max15ids>" --set-status verified --db porting.db --execute

dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "<max15ids>" --set-status verified --db porting.db --execute

If audit disagrees, use explicit reason:

dotnet run --project tools/NatsNet.PortTracker -- \
  feature update <id> --status verified --db porting.db \
  --override "manual verification evidence: <short reason>"

Checkpoint Protocol Between Tasks (REQUIRED)

After each feature group task and each test-class task:

Full build:

dotnet build dotnet/

Full unit tests:

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal

Full integration tests:

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/ --verbosity normal

Commit the task slice before moving on.

ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)

Forbidden Patterns

Production code forbidden:

throw new NotImplementedException()
return default; / return null; placeholders not present in Go logic
Empty public method bodies used as placeholders
TODO, PLACEHOLDER, or equivalent unresolved markers

Test code forbidden (for tests marked verified):

Assert.True(true)
Assert.Pass()
String/self-assertions unrelated to behavior
Empty method body without [Fact(Skip = ...)]
Any test that does not exercise production code path

Hard Limits

Max 20 features per task group.
Max 15 IDs per status update command.
Max 1 feature group promoted per verification cycle.
No feature gets verified without passing test gate evidence.
No test gets verified if skipped.

If You Get Stuck (Explicit Protocol)

Do not stub. Do not fake-pass tests.

Keep item deferred.
Add concrete blocker reason (server runtime, cluster harness, missing infra dependency, etc.).
Capture evidence command output proving blocker.
Continue with next unblocked item.

Commands:

dotnet run --project tools/NatsNet.PortTracker -- \
  feature update <id> --status deferred --db porting.db \
  --override "blocked: <specific reason>"

dotnet run --project tools/NatsNet.PortTracker -- \
  test update <id> --status deferred --db porting.db \
  --override "blocked: <specific reason>"

Task 1: Build Constructor/Test Harness Foundation (Group 01 baseline)

Files:

Modify: dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamErrors.cs
Create: dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamErrors.GeneratedConstructors.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamErrorsTests.cs
Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamErrorsGeneratedConstructorsTests.cs
Create: tools/generate-jetstream-errors.sh (or equivalent deterministic generator script)
Modify: porting.db

Step 1: Mark Group 01 as stub (<=15 IDs per command)

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "1751,1752,1755,1756,1757,1758,1759,1760,1761,1762,1763,1764,1765,1766,1767" \
  --set-status stub --db porting.db --execute

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "1768,1769,1770,1771,1772" \
  --set-status stub --db porting.db --execute

Step 2: Write failing tests for Group 01 constructor surface + helper parity

Add failing coverage for:
- Unless/ParseOpts override behavior
- ToReplacerArgs parity conversions (string, Exception, generic object)
- Group 01 constructor method existence and output parity

Step 3: Run focused tests to confirm FAIL

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~JetStreamErrorsGeneratedConstructorsTests.ConstructorSurface_Group01" --verbosity normal

Step 4: Implement Group 01 methods + helper parity

Implement mapped helper methods (ParseOpts, ToReplacerArgs) and Group 01 constructors.

Step 5: Re-run focused tests and confirm PASS

Step 6: Run stub scan + build gate + test gate

Use protocol commands above.

Step 7: Promote Group 01 statuses to complete then verified

Use the same two ID chunks as Step 1, first complete, then verified.

Step 8: Checkpoint + commit

git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamErrors.cs \
        dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamErrors.GeneratedConstructors.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamErrorsTests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamErrorsGeneratedConstructorsTests.cs \
        tools/generate-jetstream-errors.sh porting.db

git commit -m "feat(batch5): implement jetstream error helpers and group01 constructors"

Task 2: Implement Feature Group 02 (20 features)

IDs: 1773-1792

Files:

Modify: dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamErrors.GeneratedConstructors.cs
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamErrorsGeneratedConstructorsTests.cs
Modify: porting.db

Execution Steps (repeat pattern for this and all later feature groups):

Set stub in <=15 chunks:
- 1773,1774,1775,1776,1777,1778,1779,1780,1781,1782,1783,1784,1785,1786,1787
- 1788,1789,1790,1791,1792
Add/enable failing Group 02 tests.
Run Group 02 focused tests and confirm fail.
Implement constructors for Group 02.
Run Group 02 focused tests and confirm pass.
Run stub scan + build gate + test gate.
Set complete in same 2 chunks.
Set verified in same 2 chunks.
Run checkpoint protocol and commit.

Task 3: Implement Feature Group 03 (20 features)

IDs: 1793-1812

Status chunks:

Chunk A: 1793,1794,1795,1796,1797,1798,1799,1800,1801,1802,1803,1804,1805,1806,1807
Chunk B: 1808,1809,1810,1811,1812

Follow Task 2 steps verbatim (stub -> failing tests -> implementation -> pass -> gates -> complete -> verified -> checkpoint commit).

Task 4: Implement Feature Group 04 (20 features)

IDs: 1813-1832

Status chunks:

Chunk A: 1813,1814,1815,1816,1817,1818,1819,1820,1821,1822,1823,1824,1825,1826,1827
Chunk B: 1828,1829,1830,1831,1832

Follow Task 2 steps verbatim.

Task 5: Implement Feature Group 05 (20 features)

IDs: 1833-1852

Status chunks:

Chunk A: 1833,1834,1835,1836,1837,1838,1839,1840,1841,1842,1843,1844,1845,1846,1847
Chunk B: 1848,1849,1850,1851,1852

Follow Task 2 steps verbatim.

Task 6: Implement Feature Group 06 (20 features)

IDs: 1853-1872

Status chunks:

Chunk A: 1853,1854,1855,1856,1857,1858,1859,1860,1861,1862,1863,1864,1865,1866,1867
Chunk B: 1868,1869,1870,1871,1872

Follow Task 2 steps verbatim.

Task 7: Implement Feature Group 07 (20 features)

IDs: 1873-1892

Status chunks:

Chunk A: 1873,1874,1875,1876,1877,1878,1879,1880,1881,1882,1883,1884,1885,1886,1887
Chunk B: 1888,1889,1890,1891,1892

Follow Task 2 steps verbatim.

Task 8: Implement Feature Group 08 (20 features)

IDs: 1893-1912

Status chunks:

Chunk A: 1893,1894,1895,1896,1897,1898,1899,1900,1901,1902,1903,1904,1905,1906,1907
Chunk B: 1908,1909,1910,1911,1912

Follow Task 2 steps verbatim.

Task 9: Implement Feature Group 09 (20 features)

IDs: 1913-1932

Status chunks:

Chunk A: 1913,1914,1915,1916,1917,1918,1919,1920,1921,1922,1923,1924,1925,1926,1927
Chunk B: 1928,1929,1930,1931,1932

Follow Task 2 steps verbatim.

Task 10: Implement Feature Group 10 (20 features)

IDs: 1933-1952

Status chunks:

Chunk A: 1933,1934,1935,1936,1937,1938,1939,1940,1941,1942,1943,1944,1945,1946,1947
Chunk B: 1948,1949,1950,1951,1952

Follow Task 2 steps verbatim.

Task 11: Implement Feature Group 11 (6 features)

IDs: 1953,1954,1955,1956,1957,1958

Steps:

Set all 6 to stub in one command.
Add/enable failing Group 11 tests.
Run focused Group 11 tests and confirm fail.
Implement constructors for Group 11.
Re-run focused tests and confirm pass.
Run stub scan + build gate + test gate.
Set all 6 to complete.
Set all 6 to verified only if linked mapped tests also pass (1953 is linked); otherwise keep linked feature at complete with blocker note.
Run checkpoint protocol and commit.

Task 12: Port/Resolve Batch 5 Mapped Tests (11 tests)

Files:

Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamBatchingTests.cs (T:742)
Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/NatsConsumerTests.cs (T:1304)
Create/Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/JetStreamEngineTests.cs (T:1476,1606,1694,1696,1708,1757,1767,1777)
Create/Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/MqttHandlerTests.cs (T:2272)
Modify: porting.db

Per-test loop (REQUIRED):

Read exact Go test body (test show <id> + source lines).
Attempt faithful C# port.
Run single-test filter and collect output.
If pass: mark test verified.
If blocked by infra: keep deferred with specific reason; do not fake-pass.

Single-test run template:

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~<ClassName>.<MethodName>" --verbosity normal

Status updates (max 15 IDs):

Verified chunk example:

dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "742,1304,1476,1606,1694,1696,1708,1757,1767,1777,2272" \
  --set-status verified --db porting.db --execute

Deferred (if blocked) per-test with reason:

dotnet run --project tools/NatsNet.PortTracker -- \
  test update <id> --status deferred --db porting.db \
  --override "blocked: requires running JetStream/MQTT server harness parity"

Checkpoint after each test class and one commit at task end.

Task 13: Batch 5 Final Verification and Closure

Files:

Modify: porting.db
Generate: reports/current.md

Step 1: Full gates

dotnet build dotnet/
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/ --verbosity normal

Step 2: Batch-level audit checks

dotnet run --project tools/NatsNet.PortTracker -- audit --type features --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- audit --type tests --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- batch show 5 --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db

Step 3: Global stub scan for touched areas

rg -n "NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|Assert\.Pass\(" \
  dotnet/src/ZB.MOM.NatsNet.Server/JetStream \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server

Step 4: Complete batch only if all items satisfy allowed terminal states

dotnet run --project tools/NatsNet.PortTracker -- batch complete 5 --db porting.db

If blocked by deferred tests/features, do not force completion; leave explicit blocker notes.

Step 5: Generate report + commit

./reports/generate-report.sh
git add dotnet/src/ZB.MOM.NatsNet.Server/JetStream \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server \
        tools/generate-jetstream-errors.sh \
        porting.db reports/
git commit -m "feat(batch5): port jetstream error constructors and verify mapped tests"

17 KiB Raw Blame History

Batch 5 (JetStream Errors) Implementation Plan

Batch 5 Working Set

MANDATORY VERIFICATION PROTOCOL

Per-Feature Verification Loop (REQUIRED for every feature ID)

Stub Detection Check (REQUIRED after every feature group and test class)

Build Gate (REQUIRED after each feature group)

Test Gate (REQUIRED before marking any feature verified)

Status Update Protocol (REQUIRED)

Checkpoint Protocol Between Tasks (REQUIRED)

ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)

Forbidden Patterns

Hard Limits

If You Get Stuck (Explicit Protocol)

Task 1: Build Constructor/Test Harness Foundation (Group 01 baseline)

Task 2: Implement Feature Group 02 (20 features)

Task 3: Implement Feature Group 03 (20 features)

Task 4: Implement Feature Group 04 (20 features)

Task 5: Implement Feature Group 05 (20 features)

Task 6: Implement Feature Group 06 (20 features)

Task 7: Implement Feature Group 07 (20 features)

Task 8: Implement Feature Group 08 (20 features)

Task 9: Implement Feature Group 09 (20 features)

Task 10: Implement Feature Group 10 (20 features)

Task 11: Implement Feature Group 11 (6 features)

Task 12: Port/Resolve Batch 5 Mapped Tests (11 tests)

Task 13: Batch 5 Final Verification and Closure

17 KiB

Raw Blame History

Test Gate (REQUIRED before marking any feature `verified`)