[lorenzocorallo]

Stacked on #116. Emanation and notifications (spec decision 10.4 and 12), plus the deleghe emails.

Emanation (emanation/service.ts)

emanation.start({ draftId }) ("Emana e notifica"):

• modifica: regulations:manage, approved, with a ready diff.
• rettifica: regulations:rectify or an active delega. It skips approval: it freezes the live text (it must
  parse), records the rettifica delibera (today; onBehalfOf = the Segretario when acting on a delega) and
  generates the diff first. On any failure it undoes all of this.

Then a resumable state machine, every step idempotent:

1. pr: commit the generated sources (applyDelibera sets \approvazione / \rettifica[delegato]) under the
   document dir, deleting sources that disappeared, on regolamenti/<doc>-<draft>. Open the PR (title,
   delibera, LLM categories, "non modificare a mano") and enable auto-merge (squash; if the checks have
   already passed, merge directly). No review: the approval happened in the dashboard.
2. checks, then merge: wait for CI and the merge (a webhook, or the 30 s cron). A CI failure or a PR closed
   without merging fails the step.
3. tag: <tagPrefix>vYYYY.MM.DD from the delibera date, .2, .3… when it's taken. It's pushed with the
   installation token, so it starts the legal release workflow. Creates the version (generated sources,
   commit, assets) and sets the draft emanata.
4. release: wait for the release with the official PDF (legal.json outputs.pdf), upload
   differenze-<tag>.pdf (re-rendered with the tag and the delibera), and keep the official PDF as the version's
   PDF (versions.pdf).
5. email: to REGULATIONS_EMAIL_TO (soci@) from REGULATIONS_EMAIL_SENDER (still to be decided; defaults to
   the existing sender), with Reply-To REGULATIONS_EMAIL_REPLY_TO (direttivo@). React Email template: delibera,
   tag, release link, dashboard link, categories, the 10-day deadline for a modifica, and the differences PDF
   attached. Its time is notifiedAt, which starts the opposition window. For a rettifica on a delega, the
   Segretario who granted it gets a notice.
6. telegram: postRegulation to REGULATIONS_TELEGRAM_CHAT_ID/_TOPIC_ID (pending from Lorenzo; skipped while
   unset) with the official PDF and the differences PDF.

• Every send goes through sendOnce: recorded before (pending) and after (sent: time, recipients, attempts), keyed,
  so a resumed step never sends twice. emanation.get shows the steps (state, url, at, detail) and the
  notifications. emanation.retry resets failed steps and resumes.
• Deleghe: creating or revoking one emails REGULATIONS_DIRETTIVO_EMAIL (Statuto, art. "Direttivo", comma 9).
• The diff can't be regenerated once the emanation has started.

GitHub (emanation/github.ts)

• githubAppClient: Octokit App from REGULATIONS_GITHUB_APP_ID / _PRIVATE_KEY (the App isn't created yet),
  finding the installation on REGULATIONS_GITHUB_REPO. It uses the git data API (blobs, tree, commit, ref),
  pulls, check runs, the GraphQL enablePullRequestAutoMerge, tags, releases, and asset upload and download.
• githubLegalSource: documents.sync reads legal.json and the document from GitHub in production.
• POST /github/webhook checks the HMAC (REGULATIONS_GITHUB_WEBHOOK_SECRET) and resumes the emanation on
  pull_request, check_suite and release events. The backend is in-cluster only, so the webhook is optional; the
  30 s poll covers it.
• fakeGitHub: an in-memory repository. CI passes after a delay, auto-merge merges, and a tag gets a release
  whose "CI" compiles the official PDF with the worker in the dev stack. It's the default outside production, and
  keeps its state across restarts in development (REGULATIONS_FAKE_GITHUB_STATE).

Telegram (websocket/telegram.ts)

The new postRegulation command, with the shape agreed with the telegram thread (PostRegulation: chat, topic,
Telegram HTML text, structured fields, files as Uint8Array). The bot acks with cb(null, { messageIds }) and a
failure is retried. A small registry lets the regulations module reach the socket server without importing the
entrypoint.

Verified

• tests/regulations-emanation.fixture.ts (Postgres + fake GitHub, wrapped by regulations-emanation.test.ts):

  • Modifica: the Direttivo is refused; the Presidente starts it; the PR auto-merges after CI; main has the
    edited sources and \approvazione{direttivo}{2026-11-09}; tag sample-v2026.11.09; the release gets
    differenze-…pdf; the version has the PDF and release URL; the draft is emanata with the opposition
    deadline.
  • Bot down: the email is sent once (Reply-To direttivo@, 1 attachment) and Telegram fails. retry posts both
    PDFs and doesn't email again. The records show email sent ×1, telegram sent after 2 attempts.
  • Rettifica by a delegate the same day: tag .2; \rettifica[Davide Delegato]{…} next to the kept
    approval; the delega created/used emails; no opposition line.
  • It caught a real bug: Bun returns date columns as Date, which gave the tag "Mon Nov 09".

• Live, on the local stack (build(regulations): run the editor's whole stack locally #115) with the real RRI: draft A (approved through the admin UI) emanated over HTTP:

  1. PR feat: separate npm package from the backend code #1;
  2. CI;
  3. auto-merge;
  4. tag rri-v2026.11.02;
  5. release whose official PDF the worker compiled ("Approvato dal Consiglio Direttivo il 02/11/2026" printed by
     legal's \delibera);
  6. email via the dev mailer;
  7. Telegram skipped (not configured).

  The version list shows v2026.11.02 with its PDF.

• Not verified:

  • githubAppClient against GitHub: the App doesn't exist yet, and it needs Lorenzo.
  • postRegulation against the real bot: that's the telegram thread's side.
  • Graph email from the production sender.

Added while the admin thread tested end to end

• Superseded base: a draft whose lineage starts from an older version than the latest one, without that
  version merged in, would undo what was published since. Found by the admin thread on a real draft. Sending to
  approval and emanating (rettifiche included) are now refused with "La bozza parte da una versione superata (…): unisci prima la versione in vigore …", shown as the transition's blockedBy.
• can.emanateBlockedBy on drafts.get (a contract addition): why emanation is unavailable right now
  (superseded base, text that doesn't parse, missing or pending diff).
• emanation.retry on a waiting emanation re-checks GitHub immediately.
• The email links to the dashboard's diff view, …/dashboard/regulations/drafts/{draftId}/diff (overridable with
  REGULATIONS_WEB_URL).
• tests/regulations-github.fixture.ts drives the real githubAppClient against a local imitation of the GitHub
  API:
  • an RSA App key, then an installation token;
  • a git data API commit that deletes removed sources and isn't repeated;
  • the PR, then squash auto-merge via GraphQL;
  • the tag;
  • release assets uploaded and downloaded byte for byte.
• On the local stack, the admin thread emanated two more drafts through the dashboard: a modifica merged up to
  the version in force (rri-v2026.11.03) and a delegate's rettifica (rri-v2026.11.03.2). Both finished,
  including after backend reloads (the fake GitHub persists to disk; the 30 s poll resumes emanations).

Public routes (decided by Lorenzo) and Telegram follow-ups

• /public (src/public): the backend's only public surface, routed by polinetwork-cd feat: option to hide groups from search #32 (api.polinetwork.org,
  PathPrefix(/public/) with a plain-segment regex).
  • One registry (buildPublicRoutes). Each route has its own auth, body limit and rate limits (per minute, total
    and per client). tests/public-routes.test.ts lists them, so a new public route fails the tests until it's
    listed.
  • A guard runs before every other route. A path that touches /public must be the exact plain path of a declared
    route.
  • Bun resolves .. and %2e%2e before the app sees the path, so /public/../api/trpc arrives as /api/trpc.
    For that case, requests marked by the public ingress (X-PoliNetwork-Ingress, set by Traefik; requested on
    feat: option to hide groups from search #32) only ever reach declared routes.
• POST /public/webhooks/github:
  • X-Hub-Signature-256 HMAC compared in constant time with REGULATIONS_GITHUB_WEBHOOK_SECRET; 404 while the
    secret is unset;
  • X-GitHub-Delivery handled once, recorded in common_webhook_deliveries (migration 0034); a failed one is
    forgotten, so GitHub's redelivery works;
  • 1 MiB body limit; 120/min total and 60/min per client;
  • drives emanations on pull_request, check_suite, check_run and release.
• Polling is now a reconciliation every REGULATIONS_RECONCILE_SECONDS (default 300; 15 in the dev stack, whose
  fake GitHub sends no webhooks). Deliveries older than a week are pruned daily.
• Telegram (telegram#161):
  • postRegulation files are now base64 (files[].base64). A Uint8Array in the payload never reaches the bot
    through this Socket.IO engine (binary attachment frames are lost; verified with socket.io-client acting as the
    bot, on websocket and polling).
  • Each post carries idempotencyKey = the notification row id, the same on every retry.
  • The ack is read from socket.timeout(60_000).emit(…, (timeoutErr, error, result) => …).
• Verified:
  • tests/public-routes.test.ts:
    • the route list;
    • 12 hostile paths;
    • a signed delivery handled once, the replay ignored;
    • wrong, missing and truncated signatures rejected;
    • redelivery after a failure;
    • 413 and 429 limits;
    • 404 without a secret.
  • tests/public-webhook.fixture.ts: a real Bun server, Postgres, raw request targets.
  • tests/regulations-telegram.fixture.ts: the real WebSocketServer and a bot client; a 400 KB file arrives intact
    with the key; the ack returns the message ids; the bot's error surfaces.
  • The emanation fixture checks that a failed post and its retry carry the same key.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• 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

• X
• Mastodon
• Reddit
• LinkedIn

CodeRabbit Verify

• Run CodeRabbit Verify to test the changes in this pull request.