Skip to content

feat: add AIT retention capability primitives - #116

Merged
imjlk merged 13 commits into
mainfrom
codex/ait-retention-capabilities
Jul 22, 2026
Merged

imjlk merged 13 commits into
mainfrom
codex/ait-retention-capabilities

Conversation

@imjlk

@imjlk imjlk commented Jul 22, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add provider-neutral promotion reward capabilities to the platform gateway and bridge
  • add Apps in Toss SDK 3 promotion grant, pending-grant reconciliation, and notification agreement support
  • add a server-only Apps in Toss partner API client for mTLS user-key verification and functional messages
  • document Cloudflare mTLS binding integration and production trust boundaries

Safety

  • promotion grants require a server-authorized claim and persist ambiguous provider outcomes instead of retrying blindly
  • pending grants are reconciled through an injected server resolver and validated before completion
  • partner API responses are streamed with a byte limit, decoded as strict UTF-8, and parsed through exact success envelopes
  • mTLS material remains deployment-owned and is never included in client bundles

Verification

  • pnpm check
  • pnpm build:packages
  • pnpm --filter @mpgd/game-services test
  • pnpm --filter @mpgd/adapter-ait test
  • pnpm graph:game-services
  • per-commit Open Code Review, with follow-up findings patched and re-reviewed

Summary by CodeRabbit

  • New Features
    • Added promotion rewards capability end-to-end, including availability checks, reward granting with idempotency, and pending-state reconciliation.
    • Added native-backed Apps in Toss notification agreement/subscription status and subscription requests.
    • Introduced an Apps in Toss partner API client with mTLS-based anonymous-key verification and functional message sending, and exposed it via the package exports.
    • Extended bridge/platform and Cloudflare Pages handling for promotion-related methods.
  • Documentation
    • Added guidance for server-side Apps in Toss evidence, functional messages, and platform/ownership boundaries.
  • Tests / Chores
    • Expanded adapter and partner API test coverage; updated the configured Go toolchain and environment settings.

@coderabbitai

coderabbitai Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 777593d8-fb93-484f-9b12-3be88a693560

📥 Commits

Reviewing files that changed from the base of the PR and between c8a1ddc and 326050d.

📒 Files selected for processing (6)
  • .mise.toml
  • adapters/ait/src/host.test.ts
  • adapters/ait/src/host.ts
  • docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md
  • packages/game-services/src/apps-in-toss-partner-api.test.ts
  • packages/game-services/src/apps-in-toss-partner-api.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md
  • packages/game-services/src/apps-in-toss-partner-api.test.ts
  • adapters/ait/src/host.test.ts
  • adapters/ait/src/host.ts
  • packages/game-services/src/apps-in-toss-partner-api.ts

📝 Walkthrough

Walkthrough

The change adds promotion reward contracts and AIT host reconciliation, notification agreement support, an Apps in Toss mTLS partner API client, bridge fallbacks, tests, documentation, release changesets, and a Go toolchain update.

Changes

Promotion and notification platform flows

Layer / File(s) Summary
Promotion contracts and bridge routing
packages/platform/src/index.ts, packages/bridge/src/*, adapters/ait/src/index.ts
Promotion availability and reward methods are added across platform, bridge, Cloudflare Pages, AIT gateway, and sandbox implementations.
AIT host promotion and notification orchestration
adapters/ait/src/host.ts
The host handles notification agreement, promotion authorization, persisted claim reconciliation, native grants, receipt caching, configuration, and validation.
Promotion and notification behavioral coverage
adapters/ait/src/*.test.ts
Tests cover notification sessions and promotion idempotency, authorization, pending claims, receipts, corruption, and sandbox responses.
Notification delivery boundaries
docs/*.md
Documentation describes client agreement, server-side mTLS messaging, delivery ownership, and deployment boundaries.
Promotion release metadata
.sampo/changesets/ardent-runesinger-joukahainen.md
A minor release changeset covers platform, bridge, and AIT promotion and notification additions.

Apps in Toss partner API

Layer / File(s) Summary
Partner API contracts and client operations
packages/game-services/src/apps-in-toss-partner-api.ts
A typed mTLS client supports anonymous-key verification and functional-message delivery with validated response envelopes.
Partner API safety and normalization
packages/game-services/src/apps-in-toss-partner-api.ts
Inputs, HTTPS URLs, timeouts, response sizes, UTF-8 decoding, and abortable requests are validated and constrained.
Partner API package exposure and tests
packages/game-services/package.json, packages/game-services/src/*
The client is exported, included in the test script, and covered by request, response, error, and safety tests.
Partner API release metadata
.sampo/changesets/focused-mtls-messenger.md
A minor release changeset documents the new game-services client.

Toolchain configuration

Layer / File(s) Summary
Go toolchain configuration
.mise.toml
The configured Go version is updated to 1.26.5 and TTSC_GO_BINARY is defined from GOROOT.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PlatformGateway
  participant AitHostBridge
  participant AuthorizationHook
  participant NativeRewardProvider
  participant Storage
  PlatformGateway->>AitHostBridge: grantReward(campaignId, idempotencyKey)
  AitHostBridge->>Storage: reconcile persisted claim
  AitHostBridge->>AuthorizationHook: authorize claim
  AitHostBridge->>Storage: save pending marker
  AitHostBridge->>NativeRewardProvider: grant promotion
  NativeRewardProvider-->>AitHostBridge: receipt
  AitHostBridge->>Storage: save receipt
  AitHostBridge-->>PlatformGateway: reward result
Loading
sequenceDiagram
  participant GameService
  participant PartnerApiClient
  participant MtlsFetcher
  participant AppsInTossApi
  GameService->>PartnerApiClient: verify key or send functional message
  PartnerApiClient->>MtlsFetcher: POST JSON over mTLS
  MtlsFetcher->>AppsInTossApi: API request
  AppsInTossApi-->>MtlsFetcher: response envelope
  MtlsFetcher-->>PartnerApiClient: response
  PartnerApiClient-->>GameService: verification or delivery result
Loading

Possibly related PRs

  • imjlk/mpgd-kit#21: Adds the Cloudflare Pages bridge foundation extended here with promotion methods.
  • imjlk/mpgd-kit#102: Provides the AIT host bridge foundation extended with notification and promotion requests.

Poem

A bunny hops where rewards now flow,
With tiny claims reconciled just so.
mTLS messages cross the night,
Notifications bloom in flight.
Safe receipts rest in storage deep—
New platform paths help carrots leap!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title matches the main change: adding AIT retention capability primitives across the bridge and platform.
Description check ✅ Passed It covers Summary and Verification well, but the template’s Validation checklist and Notes section are missing.
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.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/ait-retention-capabilities

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

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c894c7aa92

ℹ️ 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".

Comment thread adapters/ait/src/host.ts Resolved
Comment thread adapters/ait/src/host.ts Resolved
Comment thread adapters/ait/src/host.ts Resolved
@imjlk

imjlk commented Jul 22, 2026

Copy link
Copy Markdown
Owner Author

Updated the branch with the requested authorization and reconciliation fixes.

@codex review
@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

@imjlk: Reviewing the updated authorization and reconciliation changes in #116.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f656b21d4

ℹ️ 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".

Comment thread adapters/ait/src/host.ts Resolved
Comment thread adapters/ait/src/host.ts Resolved
Comment thread adapters/ait/src/host.ts Resolved
@imjlk

imjlk commented Jul 22, 2026

Copy link
Copy Markdown
Owner Author

Patched the latest review findings in 00c0a00 and resolved the threads.

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00c0a00cfd

ℹ️ 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".

Comment thread adapters/ait/src/host.ts Resolved
Comment thread adapters/ait/src/host.ts Resolved
@imjlk

imjlk commented Jul 22, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dd57f9c8b3

ℹ️ 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".

Comment thread packages/bridge/src/index.ts Resolved
@imjlk

imjlk commented Jul 22, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (1)
packages/game-services/src/apps-in-toss-partner-api.test.ts (1)

1-236: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider adding boundary/timeout coverage.

Good coverage of the happy/error paths, but normalizeTimeout bounds, normalizeContext's 128-entry cap, normalizeBaseUrl's query/hash rejection, and the timeout/abort path in postJson/createTimeoutSignal aren't exercised. Worth adding cases, especially once the timeout-error-typing issue on apps-in-toss-partner-api.ts is addressed.

🤖 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 `@packages/game-services/src/apps-in-toss-partner-api.test.ts` around lines 1 -
236, Extend the test coverage around createAppsInTossPartnerApiClient and its
request helpers to exercise normalizeTimeout boundary values, normalizeContext
rejecting more than 128 entries, normalizeBaseUrl rejecting query strings and
fragments, and postJson/createTimeoutSignal aborting on timeout with the
expected typed error. Reuse the existing assertThrows, assertRejects, and fake
mtls fetch setup, preserving current happy-path assertions.
🤖 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 @.mise.toml:
- Line 2: Update the Go version pin in the mise configuration from 1.26.4 to
1.26.5, preserving the existing configuration format.

In `@docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md`:
- Around line 211-217: Update the documentation around sendFunctionalMessage()
and NotificationDeliveryProvider to state that Toss-user keys are trusted only
when obtained through an authenticated Toss login and user-key mapping. Clarify
that verifyAnonymousKey() does not validate Toss-user keys and that
sendFunctionalMessage() must not be treated as validation for arbitrary
toss-user keys.
- Around line 134-139: Update the fetch handler around verifyAnonymousKey to
require authenticated, authorized callers before accepting requests, and apply
rate limiting before invoking the mTLS-backed provider. Document the route as
internal-only and ensure unauthorized or throttled requests do not reach
createAppsInTossPartnerApiClient verification.

In `@packages/game-services/src/apps-in-toss-partner-api.ts`:
- Around line 135-167: Update postJson to catch failures from input.mtls.fetch
and normalize them into AppsInTossPartnerApiError, while preserving existing
AppsInTossPartnerApiError instances and their details. Ensure timeout errors
from createTimeoutSignal and other transport failures are consistently wrapped
before the existing timeout.cleanup() finally block runs.

---

Nitpick comments:
In `@packages/game-services/src/apps-in-toss-partner-api.test.ts`:
- Around line 1-236: Extend the test coverage around
createAppsInTossPartnerApiClient and its request helpers to exercise
normalizeTimeout boundary values, normalizeContext rejecting more than 128
entries, normalizeBaseUrl rejecting query strings and fragments, and
postJson/createTimeoutSignal aborting on timeout with the expected typed error.
Reuse the existing assertThrows, assertRejects, and fake mtls fetch setup,
preserving current happy-path assertions.
🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e664438d-46f7-4522-b1a8-fa40a4753e61

📥 Commits

Reviewing files that changed from the base of the PR and between 6e10d19 and c8a1ddc.

📒 Files selected for processing (17)
  • .mise.toml
  • .sampo/changesets/ardent-runesinger-joukahainen.md
  • .sampo/changesets/focused-mtls-messenger.md
  • adapters/ait/src/host.test.ts
  • adapters/ait/src/host.ts
  • adapters/ait/src/index.test.ts
  • adapters/ait/src/index.ts
  • docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md
  • docs/PLATFORM_GAME_FLOW.md
  • packages/bridge/src/cloudflare-pages.test.ts
  • packages/bridge/src/cloudflare-pages.ts
  • packages/bridge/src/index.ts
  • packages/game-services/package.json
  • packages/game-services/src/apps-in-toss-partner-api.test.ts
  • packages/game-services/src/apps-in-toss-partner-api.ts
  • packages/game-services/src/index.ts
  • packages/platform/src/index.ts

Comment thread .mise.toml Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8a1ddc719

ℹ️ 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".

Comment thread adapters/ait/src/host.ts Resolved
@imjlk

imjlk commented Jul 22, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 326050db02

ℹ️ 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".

@imjlk
imjlk merged commit 47127e7 into main Jul 22, 2026
6 checks passed
@imjlk
imjlk deleted the codex/ait-retention-capabilities branch July 22, 2026 17:15
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.

1 participant