Conversation audiences
A conversation is a message history associated with an owning company and, where applicable, a project or UE commitment. Its type identifies the intended audience. A customer dialogue, a worker dialogue and an office-only conversation on the same project remain separate histories. The office project message tab uses the customer dialogue; it is not a place for private office notes.
Access depends on the requested operation and path. A portal first checks the project or commitment relationship. The office inbox uses company capabilities and ownership or participation. Direct database requests use grants and row-level security (RLS). A visibility label or unread count does not supply permission. Publication and customer admission own the related audience and project-access rules.
Conversation families
Section titled “Conversation families”The table describes the reviewed API paths. Direct SQL has additional branches described below. UE means the subcontractor company assigned to a commitment.
| Family | Resource and intended audience | Read and write admission | Attachment boundary |
|---|---|---|---|
| Office/internal | Owning company; optional project association. Intended for backoffice collaboration. | Generic routes require selected-company conversations:read or conversations:write, then company ownership or a current company participant row. They do not independently apply every portal’s audience predicate. |
Generic attachment upload checks the same conversation scope and binds the path to the uploading company and conversation. |
project_customer |
One customer dialogue for the owning company’s project. Staff and admitted customer readers share this history. | Office project GET uses projects:read; POST uses projects:write and a staff check. Customer routes use current project admission. Customer-contact identity alone is insufficient. |
Canonical customer-conversation path; attachment signing follows an already scoped message read. |
worker_project |
One worker-facing history for a company/project, shared by qualifying workers and office readers. It is not a private thread per worker. | Worker routes require a current worker person and effective project assignment. A live direct project assignment or a live assignment to a non-deleted work order in the project can qualify. Office inbox access follows its separate capability/company path. | Worker downloads reload the assignment, conversation and exact live message, then proxy the bytes. |
project_ue |
One dialogue per commitment, owned by the principal with principal and executor company seats. Customers are not admitted through the UE route. | The selected company must be the principal or assigned executor. The principal additionally needs staff status and projects:read, including for POST. The executor path does not require the principal’s capability or a particular person seat. |
Upload/message paths bind the uploading participant company and conversation. Message reads use the shared attachment signer. |
The UE message loader checks a non-deleted commitment and its current principal and executor companies. It does not require an open commitment or an additional publication state. Do not infer message revocation from commitment closure. Other UE file and action boundaries belong to worker and subcontractor access.
Identity and request path
Section titled “Identity and request path”The accepted token selects the request’s company. Current person, company and role eligibility come from the shared live actor projection. Changing the stored Auth preference does not change an existing token’s company. A platform-administrator exception requires the selected trusted platform company, its current grant and no impersonation. This aligns the common API/SQL actor rules; it does not replace resource-specific checks. See company context and capability and resource checks.
flowchart TD Request[Authenticated request] --> Actor[Accepted token and live actor] Actor --> Office[Office API] Actor --> Portal[Customer worker or UE API] Actor --> SQL[Direct database or Storage] Office --> Company[Capability and company conversation scope] Portal --> Resource[Current project admission or assignment] Company --> Thread[Resolve the intended conversation] Resource --> Thread SQL --> Policy[Grants and operation-specific RLS] Thread --> Message[Select or create scoped message] Policy --> Message Message --> File[Check attachment binding and retrieval path]
Participant records and effective assignment
Section titled “Participant records and effective assignment”conversation_participants can name a person or a company seat with no person.
An active company seat is not an invitation for every account to use every path.
SQL person_in_conversation() requires the supplied person to be the current
person. It checks an unremoved seat in that person’s company: either the exact
person seat, or a company seat combined with conversations:read.
For a worker conversation, the helper additionally requires company ownership, a project and a current effective assignment. A stale person seat therefore does not preserve an ordinary worker’s access after the last qualifying assignment ends. Removing one work-order assignment does not revoke an independent direct project assignment or another qualifying work-order assignment.
The generic office API instead admits the owner company or a company with any unremoved participant row, after its capability guard. That test is company-wide; it does not require the caller’s exact person seat or repeat the worker predicate. The intended audience label must not be treated as an extra enforcing guard on that route. Choosing a different channel filter does not change its admission.
Direct database and MCP reads
Section titled “Direct database and MCP reads”| Path | Actual boundary | Consequence |
|---|---|---|
| Conversation rows | Owner company, participating company or explicit platform-admin branch | Seeing a conversation row does not establish permission for every message or object. |
Message SELECT (cm_select) |
Current person participates; or author company equals selected company with conversations:read; or platform-admin branch |
The author-company branch can admit a capable company reader independently of the worker membership branch. Assignment withdrawal is not a universal company-wide message revocation rule. |
| Conversation attachment SELECT | Correct bucket and person_in_conversation() for the conversation encoded in the path, or platform-admin branch |
This policy does not repeat the message policy’s author-company exception. Message and Storage decisions can differ. |
| MCP message/content reads | Conversation read permission and current inbox visibility; supplied project/conversation/message IDs are rebound before content is returned | Company inbox scope is not the customer portal’s admission rule. Audience selection narrows results after scope checks. The separate resource-audience gap remains with the MCP reference. |
These are selected read predicates, not a complete policy catalogue. A direct write must satisfy its own command’s grants, row policy and new-row checks. The API’s service-role client bypasses ordinary RLS, so route checks remain necessary. RLS explains how permissive policies combine and why a denial in one branch does not negate an allowance in another.
Conversation identity and first use
Section titled “Conversation identity and first use”Project-customer creation resolves type, project and owner company, excluding commitment and marketplace contexts. UE creation resolves type and commitment. Their shared find-or-create helper handles a unique-key race by rereading the winning row after a unique violation. The database singleton key prevents two canonical histories for those identities. Generic conversation creation returns 409 when its insert conflicts with an existing canonical customer dialogue.
Worker creation calls ensure_worker_project_conversation, which finds or creates
the worker history under a database lock and seats the worker in one transaction.
The worker finder explicitly excludes staff-only internal histories by type.
Customer and UE helpers ensure company seats separately from conversation creation. The seat’s unique key handles concurrent insert attempts. An existing removed seat is not automatically revived by that helper. Resource-based portal admission and generic participant-based inbox admission can therefore differ; do not repair participants in bulk to make the two lists look alike.
Some reads have side effects. Office/customer dialogue state and UE GET paths may
create the canonical conversation and seats; a default mark_read=true can update
a read receipt. Worker history lookup can return an empty list without creating
a conversation. A read endpoint is not necessarily a read-only database operation.
Sending, retrying and handling state
Section titled “Sending, retrying and handling state”The representative send paths validate non-empty text, bind the authenticated author and reject a non-canonical attachment path before insertion. The generic route rejects an author person different from its resolved caller. The shared message helper scopes an idempotency key to conversation, author company and author person. Reusing a key with the same text and attachment returns the existing live message; changing that payload produces a conflict. A concurrent duplicate insert rereads the winning row and compares its payload.
The HTTP header accepts 8–200 characters. If omitted, the helper generates a new key; a later request without the original key has no cross-request replay promise. There is also a narrow compatibility path for a missing idempotency column that inserts without the key. That path does not provide durable replay. Deleted messages are excluded from replay lookup; this is not a general restore contract.
sequenceDiagram participant Client participant API participant DB as Database participant Notify as Notification service Client->>API: Text attachment path and stable retry key API->>API: Admit caller and bind conversation API->>DB: Insert or find matching live message DB-->>API: Message identity or conflict API->>DB: Update handling state or draft freshness API->>Notify: Route-specific notification attempt API-->>Client: Result
Customer, worker and executor-UE inbound paths can reopen a conversation the office closed or resolved: they clear closure and snooze state and set handling status to open. Principal/office sends do not universally apply that inbound rule. The generic message route also invalidates ready AI drafts separately. A saved message, reopened room and successful notification are not one atomic operation. Route-specific notification helpers and deduplication do not establish exactly-once delivery or a transaction with an external mail service. Inspect the message identity before resending after an uncertain response.
Read receipts are per conversation and person. Unread calculations use the receipt and message times and exclude the reader’s own messages. Inbox channel, snooze, handling status, assignment to an office handler and needs-response projections organize work; they are not new permissions. Concurrent receipt writes and newly arriving messages do not form a frozen inbox snapshot.
Message and attachment scope
Section titled “Message and attachment scope”Uploading a conversation attachment stores bytes and returns a path. It does not create a message. A subsequent send must bind that path to the uploading company and the intended conversation. A path from another conversation is refused even when both conversations belong to the same company. Upload and send can fail independently and can leave an unreferenced object.
Customer, UE and office message projections sign attachments only after the conversation/message scope has been established. The shared signer removes the stored path from its returned message and normally issues a 3,600-second URL; signing failure can leave a readable message without its attachment link. Worker messages instead expose an authenticated download route that checks current assignment again. Storage and signed links owns exact bucket/path rules, URL lifetimes, uploaded-object recovery and downloaded copies.
Closing a room, ending work or withdrawing a publication can stop particular future actions. It does not recall bytes already downloaded or guarantee immediate invalidation of an issued signed URL. Posting in a conversation also does not publish the attachment as a customer project image.
Examples and recovery
Section titled “Examples and recovery”The identifiers below are synthetic. Each result names the path whose predicate it illustrates; it is not an assertion that every interface makes the same decision.
| Situation | Expected result and recovery |
|---|---|
Staff in Company A reads Project A’s customer dialogue with projects:read |
The project route admits the scoped project. Sending additionally requires its write capability and staff check. |
| The same caller substitutes Company B’s project ID without a separate relationship | The office project lookup refuses the foreign resource. A conversation ID alone does not supply project access. |
| An admitted customer opens Project A while staff have an internal and worker thread on that project | The customer projection resolves only project_customer. It does not merge the other histories. Staff should verify the displayed channel before sending. |
| Worker W loses the last live direct/work-order assignment but keeps an old conversation seat | The worker portal refuses project access; the SQL worker-membership and attachment branch also fails. An independently authorized office reader can retain access through its own path. |
| UE U opens a closed, non-deleted commitment still assigned to Company U | The UE message route retains history; an inbound executor message can reopen handling. Check the current executor and commitment, not only a closed badge. |
| A file upload succeeds but sending times out | Check whether the stable message key already produced a message. Retry the same payload/key where supported; do not assume another upload is required or that a notification failed with the insert. |
For a missing thread, first verify selected company and current person, then the requested family, resource relationship and path-specific seat/capability checks. For a missing file, verify exact message membership and canonical path before requesting another URL. Do not change project/customer relationships, revive seats or broaden permissions merely to remove an empty view.
Evidence and limits
Section titled “Evidence and limits”The worker SQL test assumes the authenticated database role with synthetic claims and exercises live assignment withdrawal and attachment/message visibility. Backend tests substitute database, Auth, Storage or notification clients for representative route, audience and replay cases; they do not exercise a live mail delivery. Inspecting these tests establishes their intended coverage, not a new execution result. The delivery PR records checks actually run and any reused evidence with matching inputs.
The November 17 actor release establishes the common live identity/context rules; it does not eliminate the resource, inbox, Storage and portal differences above. This concept claims neither universal audience parity nor atomic closure, revocation, read-state and external-notification behavior. No shared private conversation was read or sent for this review.