Skip to content

Define durable outbox dispatch contracts and keyed health adapter - #111

Merged
thomhurst merged 2 commits into
mainfrom
issue-108-outbox-contracts
Nov 1, 2026
Merged

thomhurst merged 2 commits into
mainfrom
issue-108-outbox-contracts

Conversation

@thomhurst

@thomhurst thomhurst commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

The durable outbox providers need a shared dispatch contract and a health adapter that can use scoped database services. This adds bounded row reads, expiring fenced claims, atomic completion/failure contracts, and an eligible-backlog query. The optional keyed health adapter forwards the current UTC instant and cancellation, preserves unavailable counts and database errors, and reports omitted OutboxNames entries as unhealthy.

This delivers the contract/health child of #28. Schema scripts, CLI distribution and real PostgreSQL fixtures remain in #109; database transaction implementations and dispatch workers remain planned. The site documents registration, memory ownership, claim semantics and this implementation boundary. D29 records the claim protocol without rewriting D12's history.

Closes #108

Rebased onto c6ebcfc, preserving both the merged send-tracing roadmap entry and this PR's durable-store entry. The fresh solution build exposed RLY001 in the newly merged SendTracingTests.Probe fixture. The fixture now declares [Message("send.probe")] and is public so the generated JSON context can access it. This small test-only fix restores the solution build; it has no docs impact beyond the existing contract documentation.

Validation on 0b8f99c:

  • Release solution build: 0 warnings and 0 errors.
  • Full test suite: 547 passed, 0 failed, 0 skipped. Adapter tests cover keyed names, scoped disposal, inclusive thresholds, current-time/token forwarding, cancellation, unavailable counts, errors and omitted declarations.
  • Native AOT: published for win-x64 and executed the smoke application successfully, including the scoped store adapter with reflection disabled.
  • Website: npm ci and npm run build passed on Node.js v24.14.1. The unchanged dependency audit findings remain tracked in Address documentation dependency audit vulnerabilities #101.
  • Code-simplifier review: no further behavior-preserving refinements needed. The build itself reproduces and verifies the tracing fixture fix; the new-feature tests were added alongside the contract and adapter.

No database implementation changes are claimed or validated by this PR; real database fixtures are acceptance criteria in #109.

Per-message cost: no changes to an executing message path, 0 B added per message. New runtime work occurs only during registration and health polls; no benchmark is required.

Validation evidence is archived outside the worktree at C:/git/Relayer-evidence/pr-111/0b8f99c9f4f08380be23dee9167f3669c6102627 (seven inactive days retention). It contains raw test reports, test binaries, the Native AOT executable/symbols, a source archive and build/test/site logs. inventory.csv records source paths, sizes and SHA-256 hashes for 864 files; every copy was verified against its original. source-sha256.txt records the source archive hash. This supersedes the earlier validation archive for 2e4a31f, which remains separate.

@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8f3919a5-6d3f-4797-ac04-8251edbbed9c
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

github-actions Bot commented Nov 1, 2026

Copy link
Copy Markdown

Review of #111

I read the contract changes (IOutboxStore, OutboxRecord), the keyed health adapter and its registration, the OutboxBacklogHealthCheck changes, the tests, and the docs and decision updates (D29). I didn't build the project or run the tests.

Correctness

  • The scoped keyed provider fits how health checks run. HealthCheckService resolves each check in its own scope, so the scoped IOutboxStore resolves correctly and the ValidateScopes tests cover that.
  • Registration is idempotent per name (OutboxHealthRegistration dedupe plus TryAddKeyedScoped).
  • An adapter name missing from OutboxNames fails the check instead of being silently skipped. That matches the "fail early, never degrade silently" rule.
  • Null counts, negative counts, thrown database errors and cancellation all stay distinct. A failed query is never reported as zero.
  • The claim protocol is internally consistent. Tokens are fenced and never reused, expiry is UTC, renewals never shorten an expiry, CompleteAsync and RecordFailureAsync are no-ops on an expired claim or a token mismatch, and repeated failure recording is idempotent. The remark that a complete after claim expiry returns false and may duplicate delivery is consistent with at-least-once (D9).

Performance

  • No per-message path changes. The only new work is at registration and per health poll, as the PR states, so no benchmark is needed.
  • The AOT smoke store is updated, and the code has no reflection or runtime code generation.

Docs

  • D29, the design page, the site reference and health-check guide, the roadmap and the index status are updated together. Planned work (workers, schemas) is marked as planned.

Non-blocking suggestions

  • The remarks say that providers "must reject" invalid input (empty IDs/tokens, a negative lane, a null error). Nothing in this PR enforces that. When the first provider lands in Ship PostgreSQL outbox schema, idempotent scripts and database CLI #109, a shared conformance test should assert it.
  • Because the contract lives in XML remarks only, a reusable abstract conformance suite for IOutboxStore would stop providers drifting on the claim and expiry semantics. That fits the transport conformance direction already in the design.

No blocking issues found.

@thomhurst

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-01T14:36:35.409550Z 0b8f99c Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 2e4a31fe6e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@thomhurst
thomhurst force-pushed the issue-108-outbox-contracts branch from 2e4a31f to 0b8f99c Compare November 1, 2026 14:31
@thomhurst

Copy link
Copy Markdown
Owner Author

@codex review

Rebased onto c6ebcfc and preserved both roadmap additions. The fresh build also exposed the newly merged tracing fixture's missing stable message identity; 0b8f99c adds [Message("send.probe")] and makes the fixture accessible to generated serialization metadata.

Disposition of Claude's two non-blocking suggestions in #111 (comment): provider argument validation and a reusable store conformance suite belong with executable database providers. This PR introduces the contract and health adapter only, so neither suggestion changes this head. #109 covers schema/CLI fixtures rather than a dispatch store implementation; database transaction/provider implementations remain in #29, #30 and #41. No runtime provider behavior is left untested by this PR's scope.

Validation on the new head: Release solution build passed with zero warnings/errors; all 547 tests passed; win-x64 Native AOT publish and execution passed; npm ci and the website build passed. Verified evidence and SHA-256 inventory: C:/git/Relayer-evidence/pr-111/0b8f99c9f4f08380be23dee9167f3669c6102627. Both reviewers must review this new head before promotion; the PR remains a draft.

@github-actions

github-actions Bot commented Nov 1, 2026

Copy link
Copy Markdown

Review of #111 (outbox store contract + health adapter)

I read the contract (IOutboxStore, OutboxRecord), the health adapter and its registration, and the backlog check. I did not run the build or tests; I'm relying on the PR's reported results.

  • Correctness: The claim and fencing semantics are consistent across the interface docs. The contract covers expiring tokens, a fresh token per attempt, renewal that never shortens expiry, and completion or failure only under a live matching claim. GetPendingCountAsync returns long?, so null means unavailable rather than zero, and the check maps it to Unhealthy. The adapter forwards TimeProvider.GetUtcNow() and the cancellation token. It is registered keyed and scoped, and it resolves IOutboxStore by the same key. Omitted OutboxNames entries are reported as unhealthy, so a misconfigured store can't pass silently (D16).
  • Performance: All of this is off the per-message path. Registration is idempotent, and the services.Any scan runs only at startup. The adapter is a thin pass-through, so no benchmark is needed.
  • Conventions: The public surface is interfaces and readonly record structs, and the implementation is internal. There is no reflection or assembly scanning. The PR adds decision D29, updates the docs site, roadmap and sidebar, and extends the AOT smoke test and unit tests. It also includes a small fix for RLY001 in a test fixture.
  • Non-blocking: OutboxStoreHealthProvider.GetPendingCountAsync calls ThrowIfCancellationRequested and then awaits nothing of its own. That is fine, since the store call also observes the token.

No actionable issues.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 0b8f99c9f4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown
Owner Author

Red-main follow-up: #103 merged and closed #102; that earlier lock blocker is gone. The current main failure is RLY001 at SendTracingTests.cs:348 in https://github.com/thomhurst/Relayer/actions/runs/41316547316 (5064264). This PR already fixes it by declaring the public Probe fixture with [Message("send.probe")], so a duplicate fix PR is unnecessary.

Claude CLEAR and Codex completed without findings both cover current head 0b8f99c. All review surfaces are clear; the older non-blocking suggestions were dispositioned in the previous update. Reverified all 864 archived evidence files against their originals and recorded SHA-256 hashes before promotion. Durable archive: C:/git/Relayer-evidence/pr-111/0b8f99c9f4f08380be23dee9167f3669c6102627 (seven inactive days retention). inventory.csv SHA-256: 81E8B69277E379C8C18EA935FCF659535B5F53384A2F1BEA5660DBEBB613C4AE. The source archive also matches its recorded SHA-256. Existing validation covers the Release solution build, 547 tests, Windows Native AOT and the website build. Promoting and arming this reviewed head through scripts/Enable-AutoMerge.ps1 -Pr 111 -MarkReady.

@thomhurst
thomhurst marked this pull request as ready for review November 1, 2026 14:35
@thomhurst
thomhurst enabled auto-merge (squash) November 1, 2026 14:35
@thomhurst
thomhurst merged commit 6a5f673 into main Nov 1, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define durable outbox dispatch contracts and keyed health adapter

1 participant