@voltro/plugin-chat 0.0.0-stage → 0.87.0

package/LICENSE

@@ -0,0 +1,61 @@
+Voltro — Proprietary Software License
+
+Copyright (c) 2026 Voltro UG. All rights reserved.
+
+This software and all associated source code, documentation, and other
+materials (the "Software") are the proprietary property of Voltro UG
+("Voltro"). This is NOT open-source software.
+
+Your access to and use of the Software is governed exclusively by the Voltro
+Terms of Service at:
+
+    https://voltro.cloud/legal/terms
+
+By downloading, installing, or using the Software you agree to those Terms.
+Subject to and conditioned on your continued compliance with them, Voltro
+grants you a limited, non-exclusive, non-transferable, non-sublicensable,
+revocable license to use the Software. The license covers use by your
+authorised named users only, up to the number of seats (or other billing metric)
+your plan or order covers; each named user must be an identified individual
+using their own personal account, and accounts, access credentials and seats
+must not be shared. All rights not expressly granted in the
+Terms are reserved by Voltro. If you do not agree to the Terms, you have no
+license and may not use the Software.
+
+The Terms of Service — including the scope of permitted use, plan
+entitlements, fees, and pricing — may change from time to time. The version in
+force is the one published at the URL above. Commercial terms and pricing are
+NOT part of this notice and are not fixed by, or granted in perpetuity by, the
+version of the Software in which this file appears.
+
+Permitted use — your own software. Voltro is a development framework. You may
+use the Software to build, run, and commercially distribute your own
+applications and services, and to charge your own customers for them, without
+owing Voltro any share of that revenue or any further permission beyond the
+Terms. Applications you build with the Software are yours.
+
+Prohibited use — reselling Voltro. You may NOT redistribute, resell,
+sublicense, publish, or otherwise provide the Software itself — in whole or in
+part, in source or compiled form — to third parties as a library, framework,
+SDK, template, starter, or development tool for them to build upon, whether
+standalone or repackaged. Shipping the Software as a non-separable, bundled
+dependency inside an application you deliver (for example, compiled into your
+deployed app) is permitted; extracting or re-exposing it as a reusable
+component for others is not.
+
+Except as expressly permitted above or by the Terms, you may not copy, modify,
+merge, publish, sublicense, sell, distribute, or create derivative works of the
+Software, in whole or in part.
+
+Third-party open-source components distributed alongside the Software are the
+property of their respective owners and are licensed under their own terms; see
+THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
+rights, or extends Voltro's, in those components.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+For licensing inquiries, contact Voltro UG.

package/README.md

@@ -1,3 +1,517 @@
-# Temporary Holding Version
+# @voltro/plugin-chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Take
+
+```ts
+import { chatPlugin } from '@voltro/plugin-chat'
+
+const plugin = chatPlugin()
+```
+
+The factory contributes `_voltro_chat_channels`, `_voltro_chat_members` and
+`_voltro_chat_messages` plus server-owned `_voltro_chat_retention` sweep progress, eighteen typed RPCs, seventeen client hooks, committed message
+metadata events, configuration inspection and user/guest export/erase hooks.
+SQL owns membership, history, slow-mode admission and read receipts. Verified
+human/guest subjects use stable IDs; tenant and acting identity come from the
+request. Anonymous and machine self calls are refused.
+
+Public actions are `chat.setTyping`, `dm`, `send`, `edit`, `remove`, `markRead`, `mute` and
+`configure`, `original`, `leave`, `transferOwnership`; queries are `chat.messages`, `channel`, `membership`, `channels`, `unread`. A message is an
+intention with `channelId`, `requestId`, `body`, optional `replyToId`; it never
+accepts an author, tenant or arbitrary stored row. The request ID deterministically
+identifies the committed sender intention. An exact retry reads its SQL receipt
+before consuming rates again; changed content with the same ID refuses `conflict`.
+Edits/deletes require `baseVersion`; only the author edits and an author or
+same-channel mod/owner deletes. Normal reads hide deleted bodies and server-only
+original text. The role-gated original action is written; moderator history UI remains open.
+
+## Configure
+
+| Option | Default | Meaning |
+|---|---|---|
+| `maxBodyLength` | 2,000 code points | Message input budget |
+| `pageSize` | 50 | Maximum raw history rows per page |
+| `maxMembers` | 500 | Server channel-creation member limit |
+| `maxChannelsPerSubject` | 100 | Channel-list read budget, not global membership admission |
+| `retentionMs` | 7 days | Default channel history window; null means no configured expiry |
+| `perChannelRate` | 2/s | Sender/channel attempt budget |
+| `globalRate` | 10/s | Sender attempt budget across channels |
+| `maxMentions` | 20 | Resolved mention budget |
+| `maxExportRows` | 10,000 | Complete bounded export; overflow refuses |
+| `denyWords` | empty | Explicit keyword policy; empty is no denylist coverage |
+| `moderationAction` | `block` | Refuse flagged content, or persist under `flag` |
+| `strategies` | four defaults | Named replacement rule slots |
+| `rateLimit` | Registry Redis | Existing limiter connection/HotStore options |
+| `now` | `Date.now` | Clock for rules and observations |
+
+These are configuration budgets, not measured throughput. The limiter reuses the
+Registry-backed HotStore adapter from `plugin-ratelimit`; the app owns connections.
+Missing activation, backend errors and fail-open evidence refuse sends rather
+than silently allowing them. Explicit injected HotStore state refuses activation
+when deployment evidence declares multiple nodes. Use the Registry Redis path
+for such deployments. This plugin opens no independent Redis connection.
+
+Channel `slowModeMs` and member `mutedUntil` are authoritative SQL values.
+Send admission writes the channel fence before reading membership/time, serializing
+same-channel writes across stores. Mod/owner roles control mute/configure; ordinary
+members cannot freeze a channel or mute another person. This conservative SQL
+serialization has not been measured under load.
+
+## Hook
+
+The shipped source directory discovers a guarded `chat.messageChanged` event and
+post-commit producer. Its routing key is `channelId`; payload carries only
+`messageId`, `version`, `change`. Text, author identity and media are absent.
+The listener scope is `chat:events:read`, for operators, not an authorization
+shortcut for players. The producer selects tenant from committed rows and
+suppresses unchanged-version admission writes. CDC delivery is best-effort,
+not a durable archive or business event.
+
+Normal player messages use a live query over message, channel, membership and
+Social-relation triggers. The handler verifies actual membership/tenant and
+filters authors blocked in either direction through `SocialBlockPort` before
+returning rows. Without a Social port there is no block policy to evaluate;
+DM creation refuses without that port. `canMessage` admits an existing friend
+or the recipient request policy, after block checks. Party/guild/lobby channels
+must be provisioned by trusted server integrations.
+
+`dataStoreChat(...).createChannel` permits only an internal system subject or a
+same-tenant service account with `chat:channels:write`. Its input owns kind, ref,
+name, members and roles. A cold create inserts transactionally; after a lost race
+or reply, only the exact SQL creation claim matches. Direct DM intentions construct
+one canonical pair channel after recipient admission. Retention uses bounded persisted sweep steps through `ChatAdministration.prune`
+and the contributed `chat.pruneHistory` schedule; details below. Install `plugin-audit` with its durable sink to audit
+RPC actions. Chat does not claim to have built an independent audit trail.
+
+## Channel lifecycle and match archive
+
+This additional source is built. `ChatAdministration` in
+`@voltro/plugin-chat/server` is provided by the installing plugin's normal
+service Layer. It borrows the actual bound SQL store; no independent connection
+is opened. `dataStoreChat` exposes the same administration methods for explicit
+server adapters.
+
+`addMember` and `removeMember` accept only an internal system identity or a
+same-tenant service account holding `chat:members:write`. Their inputs contain
+`tenantId`, `channelId`, `subjectId`; adding also requires `role: 'member' | 'mod'`.
+The transaction acquires the channel writer fence before reading the roster cap.
+An exact existing role is a no-op; role replacement refuses `conflict`. Adding
+an owner is not allowed. DM membership cannot change; archived match rosters do
+not admit new members. Existing owners cannot be removed through this operation.
+The global `maxChannelsPerSubject` option remains a read budget; it does not
+claim to enforce concurrent admission across different channels.
+
+`chat.leave({ channelId })` uses the authenticated human/guest identity; it is
+repeatable after removal. Owners must first call
+`chat.transferOwnership({ channelId, targetId })`, which requires an existing
+unmuted member and exactly one current owner. Demotion and promotion share the
+same SQL transaction. DM leave/transfer refuses. `useChatLeave` and
+`useChatTransferOwnership` expose these intentions through the existing mutation
+client. Subsequent channel/history/send calls re-check membership. This source
+has not established revocation of already buffered queries or active event streams.
+
+`archiveMatch(subject, input)` requires a system identity or a same-tenant service
+account holding `chat:archive:write`. Only trusted Room disposal/server integration
+may supply `tenantId`, `matchId`, `name`, `members`, and `messages` containing
+`id`, `authorId`, `body`, `at`, plus optional `retentionMs`. A browser cannot call
+this operation. The transcript is detached at invocation, validates every author
+against the supplied server roster and refuses future timestamps, duplicate IDs
+and configured budgets. It uses `maxExportRows` as the transcript entry budget;
+that number is not measured archive capacity. Every cold entry passes the actual
+moderation strategy before any SQL write. Archived text never enters a Room tick.
+
+Channel, memberships and messages commit together; the resulting match channel
+starts frozen. A deterministic complete-transcript claim and per-message SQL
+receipts admit exact retries, including different roster/message input order.
+An existing exact archive is read before calling moderation again. Changed input,
+conflicting IDs or incomplete/erased/retained-out receipts refuse rather than
+recreate history. An insert failure rolls back the whole new archive. These
+transaction and successor expectations are authored for all six native dialects,
+with memory and installed-Layer controls; none has run. This is not replay,
+report-evidence ingestion, ordinary boot or a process-restart proof.
+
+Private `chat.typing`, listener membership revocation, Party/Guild automatic
+synchronization and Room-disposal wiring remain open. The existing operator
+metadata event is not a substitute for private player delivery.
+
+## Override
+
+`./strategies` exports each single default:
+`keywordChatModeration` (`moderate`), `fixedChatRateBudgets` (`rateLimit`),
+`noResolvedChatMentions` (`mentionResolver`), `channelChatRetention` (`retention`).
+Moderation composes the existing `plugin-moderation` keyword provider before SQL.
+A custom Effect may reject, flag or replace text within the input budget; provider
+failures become an unavailable refusal. The empty default denylist performs no
+profanity classification. AI/image/provider coverage is not implied.
+
+A rate slot changes budgets, not the HotStore counter authority. Mention slots
+resolve trusted subject IDs outside SQL, then membership/block validation occurs
+before storing refs. The default resolves nothing; text is not treated as an
+identity proof. Edited text clears earlier mention refs. Retention slots return
+a bounded duration or null. The configuration panel identifies custom/default slots.
+
+## Extend or replace
+
+Chat is a leaf under the system contract: it supplies events and strategies,
+not its own replacement port. Dependencies on Social use `SocialBlockPort`,
+including a studio's alternate Layer. The three server table handles are exported;
+JSON `metadata` fields persist small extensions and exports include actual row
+columns. Static wire schemas do not yet propagate arbitrary mixin columns.
+Complete S4a propagation, custom-column UI and the system-removal command remain open.
+
+In-match chat belongs to a Room channel and never this SQL history path.
+The trusted archive adapter is written below. Storage/scan/media variants,
+sanctions reports, search, automatic party/guild membership synchronization and
+retention scheduling remain to integrate.
+No store read/write belongs in a Room tick.
+
+## Panel and GM
+
+`GET /status`, shared `ChatPage`, Local HTTP provider and Cloud authorized-app/
+replica proxy are the four authored layers. They report dated configured budgets,
+backend activation and binding, with no message/author text and no health/capacity
+claim. Channel views, rate/flag metrics, moderator history and inspect write controls
+remain to build; mute and freeze RPC admission is already authored.
+
+`./web` exports `useChannel`, `useChannelList`, `useChatMessages`, `useChatSend`,
+`useChatEdit`, `useChatRemove`. Pages use stable `(createdAt,id)` cursors in reverse
+order. A blocked raw page can return fewer visible rows while retaining its cursor.
+Typing delivery, actual server author projections, emote/media rendering, mentions completion, reports integration and moderator history UI remain open. Written cursor/components are described below.
+
+## Tests
+
+They encode guest identity, exact retry after rate exhaustion, changed intent
+refusal, ownership, mute/slow mode, moderation, block- filtered server delivery,
+stable timestamp pagination and erase/retry. Native
+PostgreSQL/MySQL/MariaDB/MSSQL/SQLite/Turso cases exercise all three tables,
+Unicode/JSON/date fields, two independent pool slow-mode and version admission,
+successor readback and privacy. Missing native connection settings fail; they do
+not silently skip acceptance. Four strategy fixtures and real generic
+`systemContractConformance` registration cover declared exports, metadata
+extension, events, table privacy and the inspect handler. Panel/proxy fixtures
+are also written.
+
+None ran.
+
+## Privacy and limits
+
+Export includes own memberships, authored messages including original content,
+own evidence captures, the identity admission row and channels where the target
+has owner membership. Erase removes membership, anonymizes/redacts authored
+message content/refs, removes the subject from structured `payload.mentions` of
+peer messages (peer text stays), clears owned channel names/metadata and
+preserves peer history. User/guest stable identity and retry are encoded by
+fixtures. Owner succession, media removal, volatile counters/event erasure and
+cross-system privacy remain to finish.
+
+### Read cursor and components
+
+SQL read receipts store (lastReadAt,lastReadId) derived from a real channel
+message. Older acknowledgements never regress, including equal timestamps.
+The chat.unread live query excludes self-authored, deleted, expired and blocked
+messages. Each channel scans at most maxExportRows raw candidates;
+truncated:true means an incomplete count. Membership lists retain the channel
+read budget. chat.original is an action restricted to same-channel mod/owner
+membership, returning retained original text. It is no general player history.
+
+The web entry additionally exports useUnread, useChatMarkRead and useChatOriginal.
+ChatPanel, variable-height windowed MessageList, controlled Composer and
+ChannelTabs reuse ui-shadcn with en/de labels, escaped text, unknown/deleted
+identity, report-ID callbacks, character budget and loading/error/empty states.
+The parent owns trusted Players projections, draft, request ID and uncertain
+pending state. Credential/tenant session scopeKey and matching dataScopeKey fence
+old data and draft/actions. Nothing auto-replays or clears after submission.
+Focused rows remain mounted; semantic row positions and a keyboard-scrollable
+viewport are provided. History updates do not auto-scroll the reader. Callers
+bound retained page caches. No visual/accessibility performance is measured.
+
+Typing, actual server author joins, emote/media rendering, mentions completion,
+reports integration and moderator history UI remain open. Native
+cursor/successor cases cover all six dialects. None ran; no acceptance evidence
+is created by this addition.
+
+## Sanctions admission
+
+When installed, Chat consults SanctionsPort for the exact channel before new
+sends and edits. A denied decision returns sanctioned; unavailable enforcement
+refuses the write. An already committed exact send retry returns its receipt;
+deletes remain allowed by normal ownership/moderation. No sanctions table is
+read directly by Chat.
+
+Production activation now source-checks the actual deployment-wide plugin grant.
+Declare actual Licensing first; development/test remains free. See the bilingual
+Licensing contract and manual update migration.
+
+`chat.membership({ channelId })` and `useChatMembership` read only the authenticated request subject’s own SQL membership. Channel and membership are checked in one transaction with exact tenant/identity predicates; role, mute and own read cursor are authoritative values. Foreign identity fields are not input. Membership and channel changes are query sources. A successful snapshot does not replace server authorization of the next action or prove immediate revocation of buffered data.
+
+The actual membership supplies `subjectId`; active hints expire after five seconds. Typing uses separate HotStore rate keys with configured channel/global budgets, writes no SQL rows and does not belong in Room ticks. Missing publisher refuses. The installed private policy checks membership at attach, then current memberships, sender state, expiry and Social blocking before each payload. Blocked/expired hints are withheld server-side; revoked recipient membership ends the stream on its next delivery.
+
+
+`useTyping(channelId | null, apiName?)` returns `{ channelId, subjects, status }`. It consumes the private event through the existing event hook, keeps at most 128 subject IDs and uses a single monotonic timer. A hint lives for at most five local seconds and never beyond its remaining server expiry at receipt. Stop hints remove a peer; gaps, non-live state, channel/API/transport changes and unmount clear the display. Future wall-clock skew cannot create an indefinite lease. The hook does not publish hints or trust display names from events; resolve names from authorized player projections.
+
+
+`ChatPanel` accepts the `useTyping` result as `typing` and checks its channel and live status before displaying it. `TypingIndicator` resolves a single name only from the supplied authorized `authors`; unknown identities use “Someone is typing”, multiple peers use a bounded count. `chatTypingLabels` supplies English/German copy. The status region stays present without moving keyboard focus. `Composer.onTyping` reports actual editable input and stops on blur, submit, empty draft, disable and unmount.
+
+Connect that callback to `useChatTypingPublisher(channelId | null, apiName?).activity`. This separate ephemeral sender captures the actual transport, has one shared in-flight slot across channel changes, a two-second active-hint interval and a one-second interruptible request timeout. It has no active queue or automatic replay; one explicit stop may follow an in-flight active hint. Channel/subject/unmount cleanup aborts the request and keeps the slot occupied through its actual finalizer. It exposes `pending` and `error`; a typing failure does not resend a message.
+
+
+Private event policies can provide a scoped `monitor`. Registration happens before admission; its completion or failure ends the stream with a redacted access error and releases the bus subscription. The callback owns no detached worker. Chat uses one shared DataStore change listener while any typing monitors exist, capped at 4096 monitors per adapter. Relevant channel/membership/block changes and reported change-stream gaps invalidate subscriptions even when no typing payload arrives. Proven unchanged read receipts and foreign-tenant changes are ignored; incomplete row images invalidate conservatively. This uses the existing external-change injection path and performs no polling. Payload visibility checks remain in place.
+
+## Authorized author names
+
+`chat.authors({ channelId, subjectIds })` and `useChatAuthors(channelId, subjectIds)`
+resolve at most 128 distinct subject IDs through the installed `PlayersPort`.
+The requester and each returned identity must be current members of this exact
+channel/tenant; Social blocks are checked in both directions. Authorization is
+rechecked after asynchronous identity resolution. This is a bounded roster
+projection, not public profile access: it returns only subject ID, the Players
+roster display name (already including `#Tag`) and an avatar storage reference.
+Missing Players/profile, former members and blocked peers produce no identity.
+The UI keeps its unknown-author fallback for retained messages from former members.
+
+Pass the result as `authors` to ChatPanel/MessageList/TypingIndicator only with
+matching channel and current subject scope. `displayName` is the complete roster
+name; do not append another tag. Names render as text; avatar references are not
+minted URLs. Profile, member, channel and Social changes are live-query sources.
+No names travel in typing payloads.
+
+## Mentions from Players
+
+The default `playerChatMentions` strategy resolves bounded `@Name#1234` tokens
+through `PlayersPort.resolveName`. Names may contain spaces; tokens start at the
+beginning of text or after whitespace/opening punctuation. Repeated resolved
+subjects collapse to one ID. `maxMentions` bounds distinct lookup intentions before
+any Players call. Missing Players/unknown names produce no mention; unavailable
+providers refuse the operation. Chat verifies sender membership before resolving
+names, and every target's actual channel membership and Social blocks inside send
+admission. Client text cannot supply an authoritative subject ID. A rejected
+nonmember/blocked mention refuses the send; it is not silently delivered.
+
+`chat.mentionCandidates({ channelId, after? })` and
+`useChatMentionCandidates(channelId, after?)` return `{ authors, after }`. Each
+page scans at most 129 roster rows and resolves at most 128 identities through
+the same authorized author projection. Use `after` even if filtering leaves
+`authors` empty. There is no whole-roster preload or unbounded prefix scan.
+Live-query sources include profiles, members, channel and Social relations. This
+is implemented; committed mention notifications remain unfinished integration
+work.
+
+## Composer mention suggestions
+
+Pass a current authorized candidate page as `mentionCandidates` to Composer or
+ChatPanel. After an `@` token, up to eight matching names from at most 128 input
+candidates appear as ordinary focusable buttons. Arrow Down moves from the draft
+to the first choice, Tab traverses controls, and Escape closes suggestions.
+Selection inserts the full roster label as text, retains the suffix and restores
+the textarea cursor. It never sends or clears the draft. Selection ranges, email
+substrings, mid-token cursors and edits exceeding the message budget are refused.
+
+`mentionsLoading` hides stale candidates. `onLoadMoreMentions` exposes an
+explicit next-page button, including empty filtered pages; the parent owns
+paging and must replace candidates on channel/identity changes. ChatPanel's
+existing scope gate hides suggestions and callbacks while data belongs to
+another subject. Disabled or pending input exposes no suggestions.
+`chatMentionLabels` provides en/de copy.
+
+## Committed mention metadata and delivery admission
+
+`chat.mentioned` is an operator-scoped event (`chat:events:read`), keyed by channel
+and recipient subject, carrying only the message ID. The existing committed SQL
+subscriber publishes it for inserted mention recipients (max100), deduplicates
+recipients and skips the sender. Edits/deletes do not resend mentions. This is
+best-effort CDC, not a durable notification or an exactly-once delivery promise.
+Consumers must deduplicate by tenant/message/recipient if necessary.
+
+`ChatAdministration.canNotifyMention(subject, { tenantId, channelId, messageId,
+recipientId })` checks the actual retained message/mention, current channel
+members, recipient notify flag and Social blocks. Only system or same-tenant
+service account with `chat:notifications:send` may call it.
+Missing/deleted/erased/expired state is ineligible; provider failures refuse.
+Recheck at actual delivery, including after quiet-hours/digest deferral. No
+transcript/name is needed in the queued payload.
+
+## Optional mention notifications
+
+`createChatMentionNotifications` from `@voltro/plugin-chat/server` composes the
+existing ChatAdministration, Notifications dispatcher and Outbox. Supply a trusted
+server `subject`, the owning app runtime's `run` executor, a getter for its actual
+NotificationService, and `outboxForTenant` returning that app's existing facade
+bound to the requested tenant. A missing/foreign durable tenant refuses delivery.
+An optional `localeFor(recipientId, tenantId)` selects generic en/de copy; neither
+message text nor author names enter the queued notification.
+
+Register the returned `deliveryGuard` under `CHAT_MENTION_NOTIFICATION_GUARD` in
+Notifications `deliveryGuards`. Export `subscriber` from an app `*.subscribe.ts`
+and `outboxHandler` from an app `*.outbox.ts`. The subscriber interprets the same
+committed recipients as `chat.mentioned`, checks current SQL admission and enqueues
+through the existing facade. Explicit trusted consumers may call `enqueue(intent)`.
+There is no automatic installation, independent connection, or fallback that skips
+missing services. The bound app runtime must include ChatAdministration and the
+same Social policy used by Chat.
+
+The existing outbox key deduplicates pending sequential repeats; retries and
+post-delivery repeats can still duplicate external effects. Subscriber delivery
+is best-effort until enqueue, not atomic with the originating message commit.
+The outbox handler rechecks admission, then uses the normal Notifications
+renderer, preferences and delivery path. The persisted delivery guard checks
+again before channels and after quiet/digest delays. Missing guards fail closed.
+Failed channels fail the outbox attempt; already delivered channels can repeat
+on retry. No exactly- once claim.
+
+## Bounded retention schedule
+
+The contributed `chat.pruneHistory` schedule runs every minute in UTC through the
+normal scheduler (`onOverlap: skip`, `backfill: latest`). Each firing performs at
+most ten `ChatAdministration.prune` steps. A step selects at most two channel IDs,
+reads at most 201 expired message identities and deletes at most 200 messages from
+one channel. It does not load message bodies. SQL owns `_voltro_chat_retention`
+progress; the cursor and deletions commit together after writer/channel admission.
+A busy channel advances to let other channels progress, then returns on a later
+sweep. `cycleComplete` means the cursor wrapped, not that every expired row is gone.
+
+System principals sweep app channels; service accounts require
+`chat:retention:write` and are limited to their exact tenant with a separate
+cursor. A null retention policy preserves history. Successor adapters resume
+persisted progress. The result is `{ deleted, channelId, remainingInChannel,
+cycleComplete }`. These are work budgets, not measured capacity or a
+deletion-latency SLA. Retention removes history/receipts; replay of a
+retained-out match archive must still refuse.
+
+## Verified report context
+
+Configure Sanctions' existing `strategies.evidenceCollector` with
+`chatSanctionEvidenceCollector` from `@voltro/plugin-chat/server`. The ordinary
+`sanctions.report` / `useReport` input supplies target, category, request ID, note
+and `{ channelId, messageIds: [anchorId] }`; no new reporting transport is needed.
+The collector borrows actual ChatAdministration from the app runtime, checks
+reporter membership, tenant and the anchor's actual author/retention, then derives
+at most 20 earlier + anchor + 20 later SQL references. Extra client context IDs,
+wrong targets and unrelated anchors refuse. Human reports remain review-only.
+
+The current `chat.context` evidence records server-observed message IDs,
+versions, timestamps and deletion markers. It contains no transcript or author
+identity. Each reference now carries a private Chat-owned evidence ID when
+author content is available. The snapshot lifecycle is described below.
+
+## Private evidence snapshots
+
+Report collection captures up to 41 actual message versions in `_voltro_chat_evidence`
+under the channel fence. Cases retain only references; author IDs, current text and
+original text stay in this server-only table. An unexpired capture of the same
+message/version is reused without extending its expiry. After expiry, a new opaque
+ID prevents old case references from pointing to a later capture. `evidenceRetentionMs`
+defaults to 30 days (maximum 365 days), independently of ordinary history retention.
+
+`ChatAdministration.readReportEvidence(subject, { tenantId, evidenceIds })` reads at
+most 41 references for system or exact-tenant `sanctions:manage`/`admin:full` operators.
+Ordinary channel membership grants no access. Expired IDs return no record; erased
+captures return redacted author/body/original fields. Captured content survives
+ordinary message edit/removal/history pruning until evidence expiry or author erasure.
+It does not copy arbitrary message payloads or media attachments.
+
+Author export includes owned captures. Erasure locks relevant channels in stable
+order, re-reads bounded ownership after admission and retries changed channel
+sets (max4), then redacts source text and snapshots together. The retention step
+also reads at most201 evidence identities/deletes at most200 expired captures;
+its result adds `evidenceDeleted` and `evidenceRemainingInChannel`. No bodies
+are loaded by the sweep.
+
+## Joining open global channels
+
+`kind: 'global'` channels may be created with an empty `members` list. Signed-in
+users and guests then join them themselves with `chat.join({ channelId })`
+(`useChatJoin` in `./web`). Join is idempotent, passes the Sanctions checkpoint,
+respects `maxMembers` (`member_limit`) and `frozen`, refuses an erased identity
+(`identity_required`) and every other channel kind (`forbidden`). Leave with
+`chat.leave`. All other channel kinds stay server-administered through
+`ChatAdministration`.
+
+## Guild and party channels
+
+Chat keeps Players, Social, Guild and Party observers in its complete query
+`source` lists and marks only these optional integration observations with
+`optionalSource`. Offline checks and both boot paths report absent providers
+visibly without treating them as stale required tables. Installing a provider
+retains all original invalidation triggers. Membership, block and roster
+authorization continue through the existing ports on every applicable read or
+write; the annotation grants no access and installs no provider.
+
+`kind: 'guild'` channels (with `refId` = guild ID) may also start without
+members. When `@voltro/plugin-guilds` is installed, its `GuildMembershipPort`
+decides access (for `kind: 'party'` with `refId` = party ID, Matchmaking's
+`PartyMembershipPort`): current guild members may `chat.join` the guild channel,
+and sending (including every mention target), reading history and media URLs
+require current guild membership, so a kicked or departed member loses access at
+once even though the Chat membership row remains. Without Guilds, guild channels
+stay server-administered through `ChatAdministration`. `chat.channel` and
+`chat.membership` refuse a departed member; `chat.channels` and `chat.unread`
+leave such guild channels out; author and mention-candidate projections skip
+departed members; typing is neither accepted from nor delivered to them.
+
+## Media messages
+
+`chat.send` accepts an optional `mediaId`: the ID of a `_voltro_storage_refs` row the
+sender uploaded through `@voltro/plugin-storage` in the same tenant. The body is then
+an optional caption. Chat refuses a ref that belongs to someone else, another tenant,
+a derivative or a password-protected file (`forbidden`/`not_found`). Without the
+storage plugin, media sends are `forbidden`.
+
+The `moderateMedia` slot decides admission. Its default, `typedChatMedia`, checks
+`mediaContentTypes` (default PNG, JPEG, WebP, GIF) and `maxMediaBytes` (default
+10 MiB, max 100 MiB). Image classification is an integration: replace the slot to
+call a provider; `{ allowed: false }` is `content_rejected`, `flagged: true` marks
+the message. Virus scanning stays in plugin-storage's upload scanner. Chat cannot
+tell whether a ref skipped that scanner (for example a resumable upload); if your
+app allows such paths, check them in `moderateMedia`.
+
+The message stores `kind: 'media'` and `payload.media` (`id`, `contentType`, `size`,
+`width`, `height`); bytes stay in storage. Readers call `chat.mediaUrl({ messageId })`.
+It checks membership, Social blocks and retention, refuses removed media except for
+channel mods/owners, and returns a storage URL valid for `mediaUrlTtlSec` (default
+300 s, max 3600 s) with `expiresAt`. Chat does this authorization itself, so keep
+chat uploads private; a public ref yields a URL that never expires. `MessageList`
+and `ChatPanel` label media rows and call `onOpenMedia(messageId)`; they never
+render a URL themselves. Editing a caption keeps the attachment.
+
+`_voltro_chat_media` records one row per media message. Erasure and history
+retention mark rows `deleting` (owner ID cleared) in the same transaction as the
+message change. `ChatAdministration.sweepMedia(subject)` then deletes at most 50
+queued blobs per step through plugin-storage, outside SQL, and keeps a blob
+while another active row references it. A storage 404 counts as done; other
+failures stay queued and are reported as `failed`. The contributed retention
+schedule runs one sweep step per minute. Known limits: if the owner attaches the
+same upload again while the sweep is deleting it, the new message can lose its
+file; failing rows are retried first, so persistent storage errors can hold back
+later rows. Export includes owned media rows within `maxExportRows`.
+
+## Erasure admission tombstones
+
+`_voltro_chat_admissions` holds one server-only row per tenant and Chat identity. Its
+ID is derived from a SHA-256 hash of tenant and subject. Every path that adds a
+membership — `createChannel` (including DMs), `addMember` and `archiveMatch` — seeds
+that row, locks it before the channel and refuses an erased identity with
+`identity_required`. Erasure locks the same row first, then the affected channels in
+stable order, and in the same transaction sets `subjectId` to null and `erased` to
+true. History retention never deletes these rows.
+
+Consequences:
+
+- An erased identity cannot rejoin Chat in that tenant. Use a new subject ID for a
+  new account. Other tenants are independent.
+- The tombstone ID is hash-derived from tenant and subject. Anyone who already
+  knows both can recompute it; treat it as pseudonymous data in your records of
+  processing.
+- Work prepared before erasure (a queued `archiveMatch` Effect, archive moderation
+  still running, a create whose reply was lost) re-checks the tombstone before it
+  writes or recovers, so it cannot recreate memberships or content.
+- Ordinary send/edit/capture take only the channel fence; erasure shares those
+  fences, so it never takes locks in the reverse order.
+- Export counts the admission row in `maxExportRows` and omits its internal fence
+  counter.
+- Message versions are SQL `INT` columns. Edit and remove refuse
+  `baseVersion >= CHAT_MAX_MESSAGE_VERSION` (2147483647); erasure redaction
+  saturates at that ceiling instead of failing.
+
+Mention redaction scans up to 100 `payload.mentions` array slots (the
+`maxMentions` ceiling) per message with `jsonField` predicates. Its query cost
+per dialect is not measured.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+We take the security of Voltro and the applications built on it seriously. This
+document explains how to report a vulnerability and what to expect in return.
+
+## Reporting a vulnerability
+
+**Please do not open public issues or discuss suspected vulnerabilities in
+public channels.** Report them privately by email:
+
+**security contact: [support@voltro.dev](mailto:support@voltro.dev)**
+(subject line: `SECURITY`).
+
+Include, where you can:
+
+- the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
+- a description of the issue and its impact;
+- a minimal reproduction or proof of concept;
+- any suggested remediation.
+
+If you'd like to encrypt your report, ask in a first plain email and we'll
+arrange a key.
+
+## What to expect
+
+- **Acknowledgement** of your report within **3 business days**.
+- An initial assessment (severity, affected surface) and a remediation plan as
+  soon as we've reproduced the issue.
+- **Coordinated disclosure:** we'll agree a disclosure timeline with you and
+  credit you in the release notes if you wish. Please give us reasonable time to
+  ship a fix before any public disclosure.
+
+We do not currently run a paid bug-bounty program, but we genuinely appreciate
+responsible disclosure and will credit reporters.
+
+## Software Bill of Materials (SBOM)
+
+A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
+published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
+security team needs it, request it at
+[support@voltro.dev](mailto:support@voltro.dev).
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
+each `@voltro/*` package receives security fixes.** Please upgrade to the latest
+release before reporting, and pin exact versions in production.
+
+## Scope
+
+In scope: the published `@voltro/*` packages and the framework's own code.
+
+Out of scope: vulnerabilities in third-party dependencies that are already
+tracked upstream (we monitor these via a production-dependency audit gate in
+CI), and issues that require a non-default, explicitly-unsafe configuration. If
+you're unsure, report it anyway — we'd rather hear about it.