feat(coordination): dispatcher core — state store + orchestration (ADR-028 D3/D6)

[susumutomita]

Summary

⚠️ Infra PR — for your review, not self-merged (new functionality in the infrastructure workspace; per the infra は PR を開くが self-merge しない directive).

Implements the pure core of #1420 / ADR-028's platform-side coordination dispatcher (D3 + D6), TDD-first — side effects DI'd, semantics delegated to the problem's plugin, platform stays a host.

• coordination-store.ts (D3) — per-event shared coordination state on the existing Deployments table (same approach as cast-event: no new table / IAM / CDK). PK=COORD#<tenantId>#<eventId> / SK=STATE / version optimistic lock. Read + version-conditional write (conflict → caller returns 409).
• coordination-dispatch.ts (D6) — orchestration: read-or-init → SDK dispatchOp (validate→apply) → optimistic-lock write → safeProjectForTeam (fail-safe projection). Store + plugin are DI'd → 100% unit-testable.
• Adds @tenkacloud/coordination-plugin-sdk to infrastructure deps.

Deliberately excluded (needs your call): the participant-handler route (POST/GET /portal/me/coordination/<eventId>) + the plugin loader, because the loader is ADR-028 D6's bundle-glob-vs-S3 decision (build-coupling/runtime trade-off that's yours). This PR lands the loading-mechanism-independent tested core first.

Test plan

• New modules: 11 tests, 100% branches/functions/lines (16/16, 5/5, 22/22) — fresh-event init, apply-on-existing, validateOp rejection, write conflict, projection read, optimistic-lock condition, CCF→conflict, non-conditional rethrow.
• infrastructure tsc --noEmit clean / biome check clean / make harness invariant 違反 0.

Regression analysis

• Additive + not yet wired: 2 new modules + 1 test. No route imports them yet, so the participant-handler bundle/behavior is unchanged. No effect on existing tests.
• COORD# PK doesn't collide with the table's DEPLOYMENT# PK schema. SDK dep already used by other (gated 100%) workspaces.

Physical impact

• NO-OP on CFn / deployed artifacts. No new CDK construct (state rides the existing Deployments table). Modules aren't bundled into any Lambda yet (route unwired), so the participant-handler artifact is also unchanged.

Relates #1420
Relates #1417

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Introduced a new inter-team coordination system for managing shared state during events
  • Added optimistic concurrency control with automatic conflict detection for concurrent team operations
  • Implemented team-specific state projections with fallback safeguards

• Tests

  • Added comprehensive test coverage for coordination store and dispatch operations

[coderabbitai]

Warning

Review limit reached

@susumutomita, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 54 minutes and 34 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 541e75d5-1033-470f-9f4f-c11412b14bd0

📥 Commits

Reviewing files that changed from the base of the PR and between a95d5e1 and cfa4038.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-dispatch.ts
• infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-store.ts
• infrastructure/package.json
• infrastructure/test/problem-deploy/coordination-dispatch.test.ts

📝 Walkthrough

Walkthrough

This PR introduces a complete coordination dispatcher system enabling inter-team state management. It adds a DynamoDB-backed store with optimistic versioning, a dispatcher that orchestrates state initialization, operation validation/application, and persistence, and comprehensive test coverage validating all operations and conflict handling.

Changes

Coordination Dispatcher and Store

Layer / File(s)	Summary
Coordination Store with DynamoDB Persistence infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-store.ts, infrastructure/package.json	Introduces DynamoDB-backed store that persists per-event shared state using partition key COORD#<tenantId>#<eventId> and sort key STATE. Exports readCoordinationState (fetches state and version, defaulting missing version to 0) and writeCoordinationState (conditional put with optimistic versioning that returns { kind: "conflict" } on concurrent modification). Adds @tenkacloud/coordination-plugin-sdk dependency.
Dispatcher Contracts infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-dispatch.ts (lines 1–39)	Imports coordination SDK utilities (dispatchOp, safeProjectForTeam). Defines CoordinationDispatchInput<Op> with tenant/event/team identifiers, operation, context, fallback projection, and timestamp. Defines CoordinationDispatchOutcome discriminated union: ok (projection), rejected (error string), or conflict.
Dispatcher Orchestration infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-dispatch.ts (lines 47–96)	dispatchCoordinationOp reads existing state or initializes from plugin.initialState, runs dispatchOp to validate/apply the operation, writes back via writeCoordinationState with optimistic versioning (handling conflict outcome), and returns a safe per-team projection. projectCoordinationForTeam reads or initializes state and returns safeProjectForTeam output without writing, using fallback projection for safety.
Store Layer Tests infrastructure/test/problem-deploy/coordination-dispatch.test.ts (lines 1–107)	Establishes test infrastructure with a counter coordination plugin and fakeStore mock that simulates DynamoDB GetCommand/PutCommand behavior. Tests verify readCoordinationState returns undefined for missing rows and defaults version to 0; writeCoordinationState performs versioned conditional puts, bumps version, maps conditional failures to conflict, and rethrows other errors.
Dispatcher Operation Tests infrastructure/test/problem-deploy/coordination-dispatch.test.ts (lines 109–166)	Tests dispatchCoordinationOp for fresh-event initialization and persistence, stateful operation application, invalid operation rejection without writes, and write-conflict surfacing. Tests projectCoordinationForTeam for read-only projection of existing state and projection of initial plugin state when store is uninitialized.

Sequence Diagram

sequenceDiagram
  participant Caller
  participant dispatchCoordinationOp
  participant readCoordinationState
  participant dispatchOp as SDK dispatchOp
  participant writeCoordinationState
  participant safeProjectForTeam as SDK safeProjectForTeam
  
  Caller->>dispatchCoordinationOp: input
  dispatchCoordinationOp->>readCoordinationState: tenantId, eventId
  alt State exists
    readCoordinationState-->>dispatchCoordinationOp: { state, version }
  else State missing
    readCoordinationState-->>dispatchCoordinationOp: undefined
    dispatchCoordinationOp->>dispatchCoordinationOp: initialize plugin.initialState
  end
  dispatchCoordinationOp->>dispatchOp: state, operation
  alt Operation valid
    dispatchOp-->>dispatchCoordinationOp: newState
    dispatchCoordinationOp->>writeCoordinationState: newState, expectedVersion
    alt Write succeeds
      writeCoordinationState-->>dispatchCoordinationOp: { kind: "ok" }
      dispatchCoordinationOp->>safeProjectForTeam: newState
      safeProjectForTeam-->>dispatchCoordinationOp: projection
      dispatchCoordinationOp-->>Caller: { ok, projection }
    else Version conflict
      writeCoordinationState-->>dispatchCoordinationOp: { kind: "conflict" }
      dispatchCoordinationOp-->>Caller: { conflict }
    end
  else Operation invalid
    dispatchOp-->>dispatchCoordinationOp: error
    dispatchCoordinationOp-->>Caller: { rejected, error }
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A coordination dance, so fine and fair,
State flows through the dispatcher with utmost care,
Optimistic locks keep conflicts at bay,
Teams sync their hearts in a Dynamo way,
Per-team projections paint truth, bright and bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main change: implementing the coordination dispatcher core (state store and orchestration logic) as part of ADR-028.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/coordination-dispatcher-core

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

infrastructure/test/problem-deploy/coordination-dispatch.test.ts (1)

155-165: ⚡ Quick win

Add a regression test for the fail-safe projection path.

The new contract here is "return fallbackProjection if projectForTeam throws", but the suite only exercises successful projections. A tiny plugin override that throws from projectForTeam would lock in that safety guarantee for both exported helpers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@infrastructure/test/problem-deploy/coordination-dispatch.test.ts` around
lines 155 - 165, Add a regression test that exercises the fail-safe projection
path by mocking projectForTeam to throw and asserting projectCoordinationForTeam
returns the fallback projection; specifically, in coordination-dispatch.test.ts
create a test similar to the existing ones that uses fakeStore (e.g., { getItem:
undefined }) and a plugin/counter override where projectForTeam throws, then
call projectCoordinationForTeam(store, counter, base, /* fallbackProjection */ {
count: 0 }) and assert the return equals the fallback ({ count: 0 }) and that no
PutCommand was sent via send.mock.calls; locate code references to
projectCoordinationForTeam and projectForTeam to implement the throw behavior
and expectations.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-dispatch.ts`:
- Around line 52-54: Before seeding fresh state with plugin.initialState,
validate that the incoming coordination context matches the event/team
identifiers you will persist: check that input.ctx exists, that
input.ctx.teamIds includes the teamId(s) expected for this event, and that
input.eventId matches any event identifier in ctx; if validation fails, reject
early. Add an explicit guard or small Zod schema right before the
readCoordinationState / plugin.initialState block (and replicate the same
validation before the later branch around lines 93–95) so you never call
plugin.initialState with a ctx that doesn't match the input.eventId or lacks the
required teamId(s).

---

Nitpick comments:
In `@infrastructure/test/problem-deploy/coordination-dispatch.test.ts`:
- Around line 155-165: Add a regression test that exercises the fail-safe
projection path by mocking projectForTeam to throw and asserting
projectCoordinationForTeam returns the fallback projection; specifically, in
coordination-dispatch.test.ts create a test similar to the existing ones that
uses fakeStore (e.g., { getItem: undefined }) and a plugin/counter override
where projectForTeam throws, then call projectCoordinationForTeam(store,
counter, base, /* fallbackProjection */ { count: 0 }) and assert the return
equals the fallback ({ count: 0 }) and that no PutCommand was sent via
send.mock.calls; locate code references to projectCoordinationForTeam and
projectForTeam to implement the throw behavior and expectations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 97eef2a0-ebaf-4347-b936-961cdf3b764d

📥 Commits

Reviewing files that changed from the base of the PR and between 1a0e1c6 and a95d5e1.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-dispatch.ts
• infrastructure/lib/problem-deploy/handlers/participant-handler/coordination-store.ts
• infrastructure/package.json
• infrastructure/test/problem-deploy/coordination-dispatch.test.ts

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.26%. Comparing base (7a865a5) to head (cfa4038).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1606      +/-   ##
==========================================
+ Coverage   93.25%   93.26%   +0.01%     
==========================================
  Files         379      381       +2     
  Lines       10447    10472      +25     
  Branches     3187     3198      +11     
==========================================
+ Hits         9742     9767      +25     
  Misses        217      217              
  Partials      488      488              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.