feat(participation): participateInHackathon use case and /hackathon join (hackathon-participation 1b/3)

[TOMOKI977]

Summary

PR 1b of 3 for change 4, hackathon-participation. It adds the participateInHackathon use case and /hackathon join <slug>. With it, an admin can now confirm participation and the bot creates the 🏆 <name> topic, posts the analysis there and pins it. The inline button comes in PR 2.

• PR 1a review fixes:

  • R3-002: the fake repo's save preserves generalMessageId and copies the row, like the D1 upserts do.
  • R3-001: a refresh regression test with a non-null generalMessageId.
  • R2-001: the ChatPublisher.post comment is back in place.
  • R2-002: the claim docs now say <=.

• src/domain/hackathon/topic.ts:

  • topicNameFor / sanitizeTopicName: 🏆 <name>, falling back to the slug. Control and format characters are stripped. The name is capped at 128 characters without splitting surrogate pairs.
  • topicLink: https://t.me/c/<id>/<thread>.

• src/domain/hackathon/argument.ts: parseJoinArgument. A bare join gets the join usage line.

• src/domain/usecases/participate-in-hackathon.ts: the steps run in this order:

  1. admin gate
  2. look up by slug
  3. probe the existing topic (ambiguous means live)
  4. compare-and-set claim
  5. create
  6. link immediately
  7. post and pin
  8. clear the button
  9. confirm in General

  After the topic is created, it never rethrows. A redelivery inside the 60 s claim is a no-op. A deleted topic is recreated.

• src/adapters/telegram/participation.ts and hackathon-commands.ts: runParticipation and the join handler. The General reply is posted safely, so a failure there cannot trigger a webhook 500.

• src/composition.ts: wires ForumTopicManager.

• Copy: all Spanish, from the catalogs.

Review

A bounded review ran at medium risk with the reliability lens, including the security checks, over all 23 changed paths. It found no severe findings. It confirmed:

• the step order and that nothing is rethrown after creation;
• the admin gate runs before any side effect;
• the team comes from the chat, never from the payload;
• sanitizing and the link format;
• that the tests are not vacuous.

Deferred warning (R3-001): no test covers a create() failure that is not a ForumTopicCreateError. That path is unreachable with the real adapter, which wraps every failure. A test will be added first in PR 2.

Tests

• Strict TDD, with 25 use-case tests, one per critical case.
• The full suite passes (997 tests) and typecheck is clean.

Operator note

The bot needs the admin right "Manage Topics" for /hackathon join to create topics. Without it, the bot replies in Spanish with the instruction and persists nothing.

🤖 Generated with Claude Code