Consolidate private Telegram identity, text, voice, and photo input

Consolidate private Telegram identity, text, voice, and photo input

Status: blocked overall — permanent source is accepted, published, and successfully dark-deployed; private HUMAN rollout preparation is eligible now, while any flag/configuration change or live Telegram/Groq/z.ai verification waits for #166 cleanup and the #128 staged rollout owner
Tags: enhancement, assistant, backend, infra, testing, data, P1, human
Parent epic: #122
Depends on: #123 storage and #125 runtime are satisfied; #128 owns the integrated rollout; #166 Phase D, canonical first-write evidence, and temporary-cutover cleanup must finish before any enablement deploy; HUMAN Telegram/Groq/z.ai configuration and one intended enabled DataOps user
Satisfied dependencies: #136/#140/#143 are complete; accepted #121/#128 source is included in successful dark deployment run 31711997388
Not a dependency: #126 todo or #127 Typefully enablement for the #121 identity/text/voice/photo acceptance; any migration/import framework or legacy Telegram handler
Blocks: none — #126/#127 source is already integrated; accepted #121 HUMAN evidence feeds #128/#122 closure
Next owner: Alexey may privately select the intended identity/test plan now; On-Call and the #128 authorized HUMAN rollout owner resume after #166 cleanup
Resume condition: #166 restores ordinary push-triggered OIDC deployment after its accepted cutover/cleanup; #128 then executes the Stage B-D controls from the final steady-state SHA
Architecture: docs/CONVERSATIONAL_AGENT_PLUGIN_ARCHITECTURE.md (accepted architecture commit 4e5402c)
Current evidence: Tester PASS, PM acceptance, accepted source 253d0f9699dae40c3774955514b2e9fe1ba2ef28, integrated rollout 9595361a0546a52a5cb90ace7df0bbdeb524866a, and successful dark deployment run 31711997388 at 794076354048f6ff3417d55d13d334caf4237cea

Outcome

Provide one permanent private-Telegram intake adapter for the conversational runtime:

• a DataOps admin explicitly binds an immutable Telegram numeric user ID to one currently enabled DataOps user;
• linked private users can use bounded text, opaque callback actions, and core session commands;
• voice notes are transcribed privately through Groq only when the voice capability is enabled;
• photos are described/OCRed privately through z.ai only when the photo capability is enabled;
• provider-derived text is staged as untrusted, shown privately, and enters the conversational runtime only after explicit use or correction;
• unlinked/revoked users and group/channel traffic fail closed without revealing private state or invoking model/media/domain work.

This issue owns intake and identity behavior only. #126 owns todo effects, #127 owns Typefully effects, #124 owns transactional approval/execution, and #128 owns the one integrated flag/deployment/canary sequence.

Current source and deployment state

The independently accepted #121 implementation is 253d0f9. The permanent maintenance/dark-rollout behavior from #128 is 9595361, with its accepted E2E repair in fe030ad and follow-up 79ed0ad. All are ancestors of successfully deployed SHA 7940763.

Normal OIDC run 31711997388 passed application checks, stack deployment, runtime seed, and production smoke. Its deploy log records the exact six dark controls:

CONVERSATIONAL_TELEGRAM_INGRESS_ENABLED=false
CONVERSATIONAL_EXECUTION_ENABLED=false
CONVERSATIONAL_ENABLED_PLUGINS=none
CONVERSATIONAL_TYPEFULLY_EXTERNAL_EXECUTION_ENABLED=false
CONVERSATIONAL_TELEGRAM_VOICE_ENABLED=false
CONVERSATIONAL_TELEGRAM_PHOTO_ENABLED=false

The former #136 deployment blocker is satisfied. This evidence proves source publication and the all-off deployed baseline; it does not prove a real identity, Telegram delivery, Groq transcription, z.ai vision result, provider secret read, or enabled rollback.

#166 is now the only application-publication sequencing blocker. Its protected phase commits must remain exact and must not acquire Telegram flags, provider configuration, identity writes, canaries, or feature source. After #166 Phase D/canonical evidence/cleanup restores ordinary push deployment, #128 may change the reviewed controls through the normal main CI/CD path. No manual app deploy is allowed.

Permanent product contract

Identity and authorization

• The webhook secret and optional allowed-chat set are ingress controls, never user authorization.
• Every private action requires from.id as a canonical numeric identity, one active IdentityBinding, and the exact linked DataOps Users row still enabled as operator or admin.
• Authenticated enabled DataOps admins alone may list/create/revoke bindings. No username, display name, chat ID, forwarded sender, header fallback, webhook identity, or caller body grants authority.
• Binding conflicts are explicit; revocation is audited and blocks the next update immediately without exposing prior context. There is no self-service identity UI.

Private text, callbacks, and sessions

• Only private chats enter identity, conversation, media, runtime, plugin, or executor work. Directed group traffic receives at most one bounded static private-chat redirect; other group/channel traffic is acknowledged without private work.
• Text, opaque callback references, and /new, /sessions, /continue, /cancel, /discard, and /help use the channel-neutral core. Raw conversation IDs, detached “yes,” /todo, /social, /podcast, and unsupported files cannot bypass proposal/approval boundaries.
• Telegram update_id plus normalized kind supplies durable idempotency. Ordered append, expected revisions, and stored output markers prevent duplicate provider/core/reply effects and stale output.
• Telegram/provider delivery with an ambiguous external outcome is never blindly retried.

Voice and photo

• Voice accepts one Telegram-owned OGG/Opus voice note up to 20 MB and five minutes, and calls Groq whisper-large-v3 at most once. Ordinary audio/documents, arbitrary URLs/paths, malformed media, timeout, and unsafe output fail closed.
• Photo accepts one Telegram-owned JPEG photo up to 10 MB/20 MP, and calls configured z.ai glm-4.6v at most once. Image documents, arbitrary URLs/paths, malformed/decompression-risk media, timeout, and unsafe output fail closed.
• Text-only ingress, voice, and photo are separately controlled. Ingress requires the conversational z.ai configuration; voice additionally requires its Groq secret ARN; photo additionally requires its purpose-specific z.ai vision secret ARN.
• Raw media is isolated below the dedicated restrictive temp root, reaches only the intended provider, never enters DynamoDB/logs/events/exports/model context, and is deleted in finally. Bounded symlink-safe orphan cleanup touches only that root.
• Transcript/OCR/description/caption is owner-private untrusted_provider_derived content. Use/correction/discard is one revision/identity/channel-bound terminal transition. Discard invokes no runtime/plugin and removes derived content; portable output excludes the private text.

Dark mode and rollback

The old compatibility premise is retired. Flag-off no longer restores legacy Telegram task/social/podcast mutation. Ingress-off authenticates, enforces the bounded update size, and performs only the accepted deadline-bounded maintenance/private-chat redirect behavior. Rollback returns to that dark maintenance state; it never restores legacy mutation, polling, or a second adapter.

Migration/import boundary

There is no Telegram identity or conversation migration stage:

• admins create/revoke permanent product bindings through the ordinary authenticated API;
• no old chat allowlist, username, podcast-bot identity, webhook record, or source-repository state is imported or treated as a binding;
• no snapshot/backfill/checkpoint/resume/rollback/orphan route or migration test belongs to this product;
• no compatibility flag may revive the legacy mutating handler.

#174's migration cleanup does not remove the permanent identity, conversation idempotency, uncertain external-effect handling, temporary-media cleanup, or portable privacy rules. Those are live product behavior, not migration machinery.

No import, export, restore, polling-bot decommission, source-repository change, or historical identity conversion is part of #121. A real binding and the resulting conversation records are intentional HUMAN-created runtime data.

Staged HUMAN release plan

#128 owns the actual integrated deployment and flag changes. #121 records the feature-specific evidence; it must not dispatch an independent deployment.

Stage A — private owner and test identity plan (eligible now)

Owner: Alexey. No AWS/provider/data call is required.

Record privately:

• the intended enabled DataOps user and admin who will manage the binding;
• the Telegram numeric identity and private chat used for the controlled test;
• which managed Telegram, conversational z.ai, Groq transcription, and z.ai vision secrets/configuration are expected;
• one multilingual OGG voice sample and one captioned JPEG photo containing no sensitive operational material;
• the evidence owner, rollback owner, test window, and redaction plan.

Do not copy numeric IDs, usernames, chat IDs, tokens, keys, secret ARNs, media, transcript/OCR, provider response, or private links into this public issue.

Stage B — final dark baseline and binding lifecycle

Owner: #128 On-Call/authorized HUMAN operator. Start only after #166 cleanup.

1. From the exact final steady-state SHA, use ordinary main CI/CD to prove the six controls remain dark and the deployed readiness/maintenance behavior is healthy.
2. Confirm the shared Telegram secret and exact optional provider secret ARN wiring/effective IAM without reading or printing secret values. Disabled media controls must perform no provider secret lookup/call.
3. Keep ingress/execution/voice/photo/Typefully external off and plugins none. Through the ordinary authenticated admin API, bind the pre-approved Telegram numeric identity to the intended enabled user.
4. Prove conflict handling, revoke it, and show the next authenticated private update fails closed without prior-context disclosure or provider/model work. Reactivate the same reviewed binding before Stage C.

Publish only sanitized status/count/config-generation evidence.

Stage C — text and isolation canary

Use #128's reviewed ordinary-deploy control change:

Telegram ingress=true
execution=false
plugins=none
Typefully external=false
voice=false
photo=false

Then prove:

1. the linked user can send private text and use /new, /sessions, /continue, /cancel, /discard, and /help;
2. duplicate update/callback delivery produces one visible/core action;
3. unsupported files/commands and detached approval text cause no domain effect;
4. an unlinked private sender fails closed without context disclosure; and
5. a directed group mention receives only the static redirect with no identity/private/provider/model/event work.

No todo or Typefully execution is part of this canary.

Stage D — one voice canary, one photo canary, reverse rollback

1. Enable voice alone in addition to Stage C. Submit the pre-approved bounded multilingual OGG note, verify one useful private Whisper preview, complete exactly one explicit use/correction/discard decision, and verify no raw audio remains. Return voice to false.
2. Enable photo alone in addition to Stage C. Submit the pre-approved bounded captioned JPEG, verify one useful private description/OCR preview, complete exactly one explicit use/correction/discard decision, and verify no raw photo remains. Return photo to false. Across the two canaries, exercise one correction/use path and one discard path; accepted automated evidence covers the remaining branches without extra live provider calls.
3. Return all six controls to the exact dark snapshot through ordinary main CI/CD. Prove authenticated maintenance behavior, no provider lookup/call, revoked/unsupported isolation, and preserved non-private lifecycle metadata.
4. Record the feature verdict for #128. Any later integrated todo/Typefully rollout remains owned by #128/#126/#127.

Do not deliberately create provider ambiguity, inspect raw runtime records, export/restore data, or use real operationally sensitive media.

Acceptance criteria

• Admin-managed numeric identity binding, private-only authorization, normalized text/callback/session input, media review lifecycle, ordering/idempotency, privacy, temp cleanup, exact secret/IAM wiring, and dark flags passed independent Tester/PM acceptance.
• #128 permanently removed legacy mutating Telegram fallback behavior and established one strict six-control rollout/dark-maintenance contract.
• Accepted #121/#128 source is on main and included in a successful normal OIDC deployment with all six controls dark, runtime seed complete, and production smoke green.
• No migration/import framework or compatibility route is required; permanent bindings are created only through the authenticated product API.
• [HUMAN] Stage A private owner/identity/media/provider/redaction plan is recorded.
• [HUMAN] After #166 cleanup, Stage B proves the final dark graph, exact managed configuration/IAM with no disabled provider call, and real bind/revoke/reactivate fail-closed behavior.
• [HUMAN] Stage C proves linked private text/session/idempotency plus unlinked/group/unsupported isolation with execution and plugins disabled.
• [HUMAN] Stage D proves one bounded real voice preview, one bounded real photo preview, cleanup/review behavior, and exact reverse rollback to all dark.

Close #121 only after all four HUMAN criteria have accepted sanitized evidence and #128 cross-links that verdict. A deployed source SHA, secret creation, binding row, flag change, provider success, or screenshot alone is insufficient.

Dependencies and handoff

• #123 is closed and supplies the permanent identity/conversation/event storage and recovery primitives.
• #125 source is integrated and supplies the static runtime/z.ai adapter. Its live conversational provider gate is coordinated by #128.
• #126 and #127 source is integrated, but their todo/Typefully provider effects are outside the #121 canaries and do not gate identity/text/voice/photo evidence.
• #124 approval/execution is not exercised by #121's plugins-none/execution-off rollout.
• #128 is the sole rollout owner and receives #121's accepted HUMAN evidence; #122 closes only after the full epic rollout.
• #136/#140/#143 are historical satisfied dependencies, not current blockers.
• #166 blocks new application configuration publication until its final cutover/cleanup restores ordinary deployment. It does not invalidate the accepted all-off run.
• #174 is complete; deleted migration machinery must not be recreated.

Out of scope

• Todo/Typefully/plugin effects, proposal approval, execution leasing, or external Typefully calls.
• Legacy /todo, /social, /podcast, direct-task mutation, polling, or compatibility fallback.
• Self-service Telegram linking, identity UI, OAuth, group collaboration, generic uploads/documents, ordinary audio, image documents, video/GIF/sticker, link fetching, or permanent memory.
• Importing/migrating old identities or conversations; modifying source repositories or podcast bots.
• Reading credentials, posting private identity/media/provider evidence publicly, importing/exporting/restoring data, or manually deploying the app.

Start with docs/CONVERSATIONAL_AGENT_PLUGIN_ARCHITECTURE.md and the accepted implementation at 253d0f9, then review the integrated rollout in #128 and cleanup dependency #166. No test file is named; done requires the authorized staged HUMAN evidence for identity, text, voice, photo, privacy, and rollback without an independent deployment.