Summary

• Problem: Discord adapter passes the raw discord.js Message object to the server, forcing server/src/index.ts to reach into message.author.id and message.author.username. Gitea and GitLab forge adapters never resolve inbound webhook senders to Archon user UUIDs, calling handleMessage without userId.
• Why it matters: Inconsistent encapsulation means every new adapter must re-decide where identity extraction lives, server/src/index.ts accumulates platform-specific branching, and upcoming team-features (GitHub App, per-user tokens) need a clean foundation.
• What changed:
  • Added DiscordMessageContext interface and changed DiscordAdapter.onMessage to pass normalized platformUserId + displayName alongside the raw Message.
  • Extended IdentityPlatform union with 'gitea' and 'gitlab'.
  • Added user-identity resolution inside GiteaAdapter.handleWebhook via findOrCreateUserByPlatformIdentity('gitea', …).
  • Added user-identity resolution inside GitLabAdapter.handleWebhook via findOrCreateUserByPlatformIdentity('gitlab', …).
  • Updated server/src/index.ts Discord handler to consume platformUserId/displayName from the context.
  • Added unit tests for Discord context normalization, Gitea user resolution, and GitLab user resolution.
• What did not change (scope boundary):
  • The shared resolveUserId helper remains in server/src/index.ts (explicitly out-of-scope per issue).
  • No DB schema changes or migrations (platform column is VARCHAR(32)).
  • No changes to web/CLI auth flows.
  • Discord thread handling, mention stripping, and conversation ID extraction remain in the server (raw Message is still exposed for those calls).

UX Journey

Before

  Discord.js              DiscordAdapter            Server
  ──────────              ──────────────            ──────
  Message ──────▶         onMessage(message)
                                                   message.author.id
                                                   message.author.username
                                                   resolveUserId('discord', …)

  Gitea webhook ──────▶   handleWebhook()
                                                   → handleMessage(…, {})
                                                   (no userId)

  GitLab webhook ─────▶   handleWebhook()
                                                   → handleMessage(…, {})
                                                   (no userId)

After

  Discord.js              DiscordAdapter            Server
  ──────────              ──────────────            ──────
  Message ──────▶         extract author.*
                          onMessage({message,
                                     platformUserId,
                                     displayName})
                                                   resolveUserId('discord',
                                                     platformUserId, …)

  Gitea webhook ──────▶   handleWebhook()
                          findOrCreateUserByPlatformIdentity('gitea', …)
                                                   → handleMessage(…, {userId})

  GitLab webhook ─────▶   handleWebhook()
                          findOrCreateUserByPlatformIdentity('gitlab', …)
                                                   → handleMessage(…, {userId})

Architecture Diagram

Before

┌─────────────────┐      raw Message       ┌─────────────────┐
│  discord.js     │ ────────────────────▶  │  Server         │
│  (Message)      │                        │  (knows author) │
└─────────────────┘                        └─────────────────┘
                                                  │
┌─────────────────┐      no userId           ┌───┘
│  Gitea webhook  │ ────────────────────▶  │ resolveUserId
│  payload        │                        │
└─────────────────┘                        └─────────────────┘
                                                  │
┌─────────────────┐      no userId                │
│  GitLab webhook │ ────────────────────▶        │
│  payload        │                               │
└─────────────────┘                        ┌──────┴──────────┐
                                           │  Core DB users  │
                                           └─────────────────┘

After

┌─────────────────┐      DiscordMessageContext   ┌─────────────────┐
│  discord.js     │ ──────────────────────────▶  │  Server         │
│  (Message)      │  {message, platformUserId,   │  (agnostic)     │
└─────────────────┘   displayName}               └─────────────────┘
        │                                               │
        │         userId                                │
        ▼         ┌─────────────────────────────────────┘
┌─────────────────┐      findOrCreateUserByPlatformIdentity
│  GiteaAdapter   │ ───────────────────────────────────────────▶
│  (extracts      │      ('gitea', …)
│   sender.login) │
└─────────────────┘
        │
        │         userId
        ▼
┌─────────────────┐      findOrCreateUserByPlatformIdentity
│  GitLabAdapter  │ ───────────────────────────────────────────▶
│  (extracts      │      ('gitlab', …)
│   user.username)│
└─────────────────┘
                                           ┌─────────────────┐
                                           │  Core DB users  │
                                           └─────────────────┘

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: L
• Scope: adapters|server|core
• Module: adapters:discord, adapters:gitea, adapters:gitlab, server:webhooks, core:types

Change Metadata

• Change type: refactor
• Primary scope: adapters

Linked Issue

• Fixes team-foundation-followup: move per-platform user-identity extraction into adapter callback signatures #1784

Validation Evidence (required)

Commands and result summary:

bun run type-check
bun run lint
bun run format:check
bun test
bun run build

• Evidence provided (test/log/trace/screenshot):
  • Type check: ✅ Pass (no new errors; pre-existing @mariozechner/pi-coding-agent errors unchanged)
  • Lint: ✅ 0 errors, 0 warnings
  • Format: ✅ All files formatted
  • Tests: ✅ 118 affected tests pass; 404 adapter-suite tests pass; 3333 total pass across 4057 tests. 724 failures are pre-existing test-pollution issues in unrelated suites.
  • Build: ✅ All packages compiled successfully (Vite, Astro, Bun)
• If any command is intentionally skipped, explain why: None skipped.

Security Impact (required)

• New permissions/capabilities? (No)
• New external network calls? (No)
• Secrets/tokens handling changed? (No)
• File system access scope changed? (No)

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Database migration needed? (No)

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios:
  • Discord adapter delivers DiscordMessageContext with correct platformUserId and displayName extracted from message.author.
  • Server Discord handler consumes destructured context without accessing message.author.*.
  • Gitea adapter resolves comment author (event.comment?.user?.login) falling back to event.sender?.login, passes resolved userId to handleMessage.
  • GitLab adapter resolves event.user?.username, passes resolved userId to handleMessage.
• Edge cases checked:
  • Gitea/GitLab findOrCreateUserByPlatformIdentity failures are caught, warn-logged, and execution continues with userId: undefined (never throws).
  • Discord bot-message filtering remains before context extraction.
• What was not verified:
  • Live Discord/Gitea/GitLab integration (unit-test coverage only); staging smoke test recommended before release.

Side Effects / Blast Radius (required)

• Affected subsystems/workflows:
  • @archon/adapters community chat (Discord) and forge (Gitea, GitLab) adapters.
  • @archon/server Discord onMessage handler.
  • @archon/core IdentityPlatform type.
• Potential unintended effects:
  • mock.module() pollution in adapter test batches if new mocks leak across files. Mitigated by existing batch splits in package.json.
  • Gitea/GitLab conversations previously unattributed will now be linked to resolved users on next webhook delivery.
• Guardrails/monitoring for early detection:
  • Adapter unit tests cover success and failure paths for user resolution.
  • Warn logs (gitea.user_resolve_failed, gitlab.user_resolve_failed) are emitted on resolution failures for observability.

Rollback Plan (required)

• Fast rollback command/path: git revert 4afb10ee && git revert 3d2ec61f
• Feature flags or config toggles (if any): None
• Observable failure symptoms:
  • Discord bot stops responding to messages (callback signature mismatch).
  • Gitea/GitLab webhooks return 500 (unhandled findOrCreateUserByPlatformIdentity import or runtime error).

Risks and Mitigations

• Risk: mock.module() pollution across test batches causes unrelated adapter tests to fail.
  • Mitigation: Adapters package already splits tests into 6 batches; all batches pass (404 total).
• Risk: Discord message.author undefined for system/webhook messages.
  • Mitigation: Discord adapter already filters message.author.bot before invoking handler; message.author is guaranteed present for non-bot messages.
• Risk: GitLab event.user missing on some malformed webhook types.
  • Mitigation: Optional chaining with if (senderUsername) guard; proceeds with userId: undefined if missing.