# CONTRACT.md — Beacon conversation desk Beacon is a self-hosted conversation desk for one business. A conversation owns customer communication; a separately raised case owns accountable work, evidence, decisions, actions, and receipts. This declaration follows the accepted conversation-desk synthesis at research commit `193279be0423cc113870ccc57bb7ee481593ff9b`. It is a Stage 1 contract declaration. The executable clause-status registry in `tests/contract-status.mjs`, with its configured evidence sources, is the current implementation record; `HANDOVER.md` describes the bounded checkpoint and remaining release work. Neither changes this contract into a 1.0 runtime claim. Security, privacy, and operational guarantees in `BASELINE.md` apply. DATA-002 supersedes BASE-DATA-003. Times are p95 at the limits in `seed.json → limits`, which remain unmeasured until a load test replaces them. Clauses marked *Policy* name a buyer-replaceable decision; a policy never relaxes an absolute privacy rule or the human approval gate. ## Scope and invariants Beacon accepts verified email and first-party web chat in 1.0. It gives a permitted team queues, customer context, private notes, separately linked Customer, Back-office, and Tracker cases, knowledge, reviewed AI preparation, evidence-backed decisions, truthful provider outcomes, receipts, reporting, and an Intercom import path. It has one compatibility edition: Intercom labels and placement may be used without importing a live autonomous Fin reply, workflow, outbound send, or provider mutation. A customer-visible send or an external provider mutation requires a signed-in operator's approval of a reviewed decision or a signed-in operator's manual resolution. No policy, setting, extension, importer, workflow, or edition can remove that gate. This gate concerns external provider mutations and customer sends; ordinary authorised internal CRUD—drafting, case creation, assignment, notes, tags, and settings—is permission-checked and audited without a separate action approval. A Tracker case is never customer shared, customer searchable, customer exported, customer notified, publicly addressed, or revealed by a policy, setting, extension, import flag, or edition. Back-office cases are private by default in 1.0; changing their customer exposure is a future contract and release change. A Customer case is customer shared and reply capable. Provider acceptance and operator approval are not provider-confirmed success. ## Home - **HOME-001 — Owner front door.** At `/`, Beacon renders the workspace name and one owner-configured description from `src/ext/config.ts`, using the configured theme, with a link to `/signin`. It renders no customer or case data, vendor pricing, feature claims, testimonials, or operational metrics. The configurable “Powered by Beacon · runeditrun.com” credit defaults on; when enabled it is a plain link and makes no request before an operator chooses it. ## Workspace and access - **OPS-001 — Granted workspace access.** A signed-in member can read or operate only the inboxes, conversations, cases, and administration grants assigned to them. Every permitted action records the acting member, time, and authorising grant. - **OPS-002 — Workspace administration.** A member with workspace-administration grant can configure workspace identity, teammates, teams, channel settings, category configuration, working schedule, and public-channel presentation. Removing the final active workspace administrator is refused with that reason. - **OPS-003 — Approval eligibility.** A member may approve or submit a manual resolution only when they hold the non-bypassable decide grant for that case type. The decision records the signed-in member and grant. *Policy: `approval.eligibility.v2`; default: permit a qualified preparer to approve their own decision; the policy may impose an additional reviewer condition or forbid self-approval but cannot admit a member without the decide grant.* - **OPS-004 — Team inbox membership.** A routing administrator can create inboxes, give members inbox membership, and select a routing mode. The recorded selection and every assignment preserve the actor and time. - **OPS-005 — Public sign-in boundary.** Customer and public paths disclose no operator, conversation, case, Tracker, evidence, or approval data until their own route-level identity check succeeds. - **OPS-006 — Conversation-scoped send grant.** A member may review, approve, or manually resolve a conversation customer send, whether or not that conversation has linked cases, only when they hold the non-bypassable conversation-send grant for its inbox. This grant cannot authorise an external-provider mutation, case action, command, or receipt. ## Customer channels - **CHAN-001 — Inbound email.** A signed, configured inbound-mail event becomes one conversation message within 60 seconds, preserving sender, recipients, subject, text and sanitised HTML bodies, attachments, provider message ID, and threading headers. - **CHAN-002 — Strict email threading.** An inbound reply joins a conversation only when its `In-Reply-To` or `References` header names a stored message of that conversation, or its signed Beacon reply token names that conversation. - **CHAN-003 — Ambiguous email.** An inbound email that CHAN-002 does not prove belongs to a conversation starts a new conversation. When its sender is a verified contact point of a known customer, the new conversation links that customer and is flagged as possibly related to that customer's most recent non-completed case. Sender or subject similarity alone never joins it to an existing conversation. - **CHAN-004 — Inbound deduplication.** Repeated delivery of one authenticated provider message ID creates one message and one set of downstream events. - **CHAN-005 — Reviewed outbound email.** A signed-in member may submit an email only from a reviewed case outcome send under ACT-013 or a reviewed conversation-scoped send under CONV-014, whether or not that conversation has linked cases. It is submitted to `mail.sender.v1` within 60 seconds with stable delivery ID, correct threading headers, and attachments within declared limits. An email recipient is a verified contact under CUST-009. - **CHAN-006 — First-party web-chat inbound.** A visitor message appends to that visitor's open conversation or starts one and appears to permitted operators within 2 seconds. A visitor has at most one open conversation. - **CHAN-007 — Reviewed web-chat outbound.** A signed-in member may submit web chat only from a reviewed case outcome send under ACT-013 or a reviewed conversation-scoped send under CONV-014, whether or not that conversation has linked cases. It reaches the authenticated visitor session or token that owns the conversation within two seconds. A disconnected visitor sees it on reconnect, and a customer with a verified email contact receives email fallback within 60 seconds only when the reviewed send permits it. - **CHAN-008 — Attachment access.** An accepted attachment keeps its original bytes and declared filename and is readable only by an authorised member, the visitor session that owns its conversation, and an approved delivery to that conversation's verified customer contact. It reaches no other recipient. - **CHAN-009 — Message delivery truth.** Every outbound customer message records queued, sent, delivered, or failed, its attempts, and a redacted provider outcome. For web chat, delivered means the visitor session acknowledged it. A transient submission failure receives at most five attempts over one hour using the same delivery ID; permanent rejection or later bounce is failed and not resubmitted. - **CHAN-010 — Automatic mail.** Automatic, bulk, list, and no-reply mail is preserved on its conversation but does not reopen it, create a case, alert a member, or invoke AI. - **CHAN-011 — Authenticated ingress.** Mail webhooks authenticate through `mail.inbound.v1` and external-provider webhooks through `operations.provider.v1` before any deduplication or mutation. An absent or invalid signature creates no message, event, action transition, or AI request and is recorded as a rejected delivery. - **CHAN-012 — Chat deduplication.** Each web-chat submission has a visitor-scoped client message ID. A retry returns its stored message and creates no duplicate message, case, alert, or AI request. - **CHAN-013 — Rejected attachments.** An oversized, disallowed, or malformed attachment stores no bytes and appears as a rejected placeholder naming its filename and reason while the rest of the message is preserved. - **CHAN-014 — Chat presence.** While web chat is connected, a typing signal from either side reaches the other within two seconds, carries no message text, and clears after 10 seconds without a keystroke. The visitor sees whether Beacon accepted or rejected each own message, and can retry a rejected message under CHAN-012 using its original client message ID. - **CHAN-015 — Operator-created conversation.** A permitted member can begin an email or first-party web-chat conversation with a verified customer contact, optionally linking an existing case. It creates no case merely because it is sent or replied to; a member raises any case explicitly under CASE-002. - **CHAN-016 — Channel scope.** Beacon's 1.0 customer channels are verified email and first-party web chat. SMS and WhatsApp are deferred adapter families; their absence from 1.0 is not an assertion that an incumbent menu lacks them. ## Reviewed outbound - **OUT-001 — Outbound message preparation.** A permitted member can prepare a one-off reviewed outbound email or first-party web-chat message, naming its audience, channel, content, and purpose. Preparation sends nothing and creates no live autonomous campaign. - **OUT-002 — Audience and schedule.** A reviewed outbound audience rule records its version and evaluation time but only prepares candidates. Before review Beacon resolves a fixed target snapshot. Each target follows exactly one path: a case-specific target has its own case, ACT-010 decision snapshot, JUDG-004 review, approval or manual resolution, delivery record, and receipt where applicable; a conversation-scoped target uses its own CONV-014 immutable per-recipient reviewed-send snapshot, whether or not that conversation has linked cases, and its delivery creates no case, action, command, or receipt. A changed audience rule or membership may create a new fixed target snapshot only before that target is reviewed; it never expands an already reviewed decision or send snapshot. - **OUT-003 — Conditional content.** A reviewed outbound decision may prepare conditional customer-safe content with a named condition and fallback. Each delivered target records the resolved branch; a fallback never fabricates a missing customer attribute. - **OUT-004 — Direct delivery.** A reviewed outbound message is delivered only through CHAN-005 or CHAN-007 after its customer-level review decision. It records delivery truth under CHAN-009 and does not become an autonomous send because it was scheduled. - **OUT-005 — Series preparation.** A member can prepare a multi-step outbound Series for review. A Series cannot activate, send a step, call a provider, or bypass per-target customer-send approval until separately declared and implemented in a later contract release. ## Web chat widget - **WIDGET-001 — Embed.** A host page embeds first-party web chat with one asynchronous script tag carrying a workspace key and nothing else. The first script is under 50KB gzipped, does not block host rendering, and every later asset comes from the Beacon deployment. - **WIDGET-002 — Visitor token.** At first interaction Beacon issues an opaque browser-stored visitor token that restores only that visitor's own conversation history on later loads and grants no operator or customer credential. - **WIDGET-003 — Allowed origin.** Every widget request is checked against configured host origins. An unlisted origin receives no conversation, customer, availability, or operator data. - **WIDGET-004 — Availability and offline capture.** The widget reports operators present only when a permitted operator has had the app focused within five minutes and the current time falls inside the configured working schedule; otherwise it shows the configured away message and expected first-reply time. The composer accepts messages in both states. An offline message remains a conversation message, asks the visitor for an email contact point to verify under CUST-009, and creates no case until a member chooses case type and reason under CASE-002. The availability request carries workspace key and no visitor token, so it sends no visitor data before first interaction. - **WIDGET-005 — Appearance.** Launcher label, accent colour, corner position, welcome message, and away message are workspace settings applied on the next widget load without changing the host embed. - **WIDGET-006 — Public previews.** Messenger and Help Center configuration may show mobile-sized previews. Such a preview is not a native mobile operator application. ## Conversations - **CONV-001 — Lifecycle.** A conversation is open, snoozed until a recorded time, or closed. A non-automatic customer message reopens a closed or snoozed conversation unless CUST-008 blocks the customer, without altering any linked case, action, or receipt. - **CONV-002 — Transcript.** An authorised member can prepare a transcript for a verified contact of that conversation's customer. It contains customer-visible messages and times only, never a private note, evidence, decision, or rationale. - **CONV-003 — Primary record and opaque identity.** A conversation is the customer communication timeline with an opaque internal conversationId; it is not publicly addressed. Its messages, internal notes, channel identity, customer context, assignment, state, and merge history remain on the conversation. - **CONV-004 — Queues and assignment.** A permitted member can assign, reassign, or unassign a conversation within a granted inbox and can select a queue view. *Policy: `conversation.assignment.v1`; default: manual assignment, initially unassigned.* - **CONV-005 — Priority and snooze.** A member can set a conversation priority and snooze it to a recorded time. Snoozing removes it from active views until the time expires or CONV-001 reopens it; each change is audited. - **CONV-006 — Customer context.** The conversation detail presents its verified customer, relevant contacts, company relationships, other conversations, and linked cases only to a member authorised for those records. - **CONV-007 — Replies and internal notes.** A member can draft a customer reply or add an internal note. Notes are visually distinct, never leave the deployment, never appear in a customer route, and never enter a customer-facing AI output. - **CONV-008 — AI reply aids.** A member may request a cited rewrite, macro-assisted draft, summary, or reply draft. It enters a review surface, is labelled AI where applicable, and cannot send itself. - **CONV-009 — Search and commands.** Permitted members can search and filter conversations and use explicit commands such as assignment, snooze, case creation, and merge. A command records its actor and does not infer a case or external action. - **CONV-010 — Conversation merge.** A member with merge grant may merge conversations only when both link the same verified customer. The member selects a canonical conversation and records a reason. The merge emits `conversation.merged.v1` naming former and canonical conversation, member, time, and reason. The losing conversation becomes a read-only merge pointer; its messages, notes, source identity, and audit history remain readable only through their original customer authorisation boundary. Every case whose originating conversation becomes non-canonical retains that origin and receives an immutable origin-merge-link audit event naming case, former origin, canonical conversation, member, time, and reason. Cases remain separate and are neither merged nor rewritten. - **CONV-011 — Workbench.** The operator Inbox presents queue navigation, a conversation list, selected timeline, composer, and customer/context panel as one conversation workbench. - **CONV-012 — Global destinations.** The operator application exposes distinct destinations for Inbox, AI preparation, knowledge, reports, outbound, and contacts. Navigation changes no work state. - **CONV-013 — Linked-case detail.** A conversation detail lists its originating and additional linked cases, including Customer, Back-office, and Tracker cases available to that member; a link does not turn the conversation into a case. - **CONV-014 — Conversation-scoped reviewed send.** A conversation may remain at zero cases and may also have linked cases. In either situation a signed-in member holding its conversation-send grant may create an immutable per-recipient reviewed-send snapshot. The snapshot names the conversation, authenticated visitor session/token or verified email recipient, channel, content, actor, review/approval or manual-resolution member, time, and stable delivery ID. It is sent once through CHAN-005 or CHAN-007, records delivery truth under CHAN-009, creates or mutates no case, provider command, case action, or receipt, and a changed recipient or content requires a new snapshot. Email requires CUST-009 verified contact; first-party web chat may target the authenticated visitor session/token that owns the conversation. ## Cases - **CASE-001 — Separate records.** A case is separately created accountable work over one required originating conversation. A new conversation starts with zero cases; a conversation may have zero or many cases. A case owns its type, lifecycle, evidence, decision, action, and receipt history. - **CASE-002 — Creation.** A permitted member creates a case from a conversation by selecting Customer, Back-office, or Tracker type and recording a reason. Inbound email, operator-created conversation, widget offline capture, or a customer reply never creates a case automatically. - **CASE-003 — Lifecycle.** A case is in exactly one of working, waiting, awaiting_approval, returned, declined, executing, action_failed, action_indeterminate, awaiting_message, notification_failed, or completed. Every transition preserves actor or feature, time, and reason. Assignment, priority, escalation, tags, and due time are independent fields that no transition clears. - **CASE-004 — Resolution queues.** Every non-completed case appears in exactly one primary queue, selected in this order: an escalation flag or action_failed, action_indeterminate, or notification_failed state is Escalated; awaiting_message is Ready to send; waiting or executing is Waiting; any other non-completed case is Needs a decision. A completed case appears in no primary queue and remains searchable and reportable. - **CASE-005 — Assignment.** A permitted member can assign and reassign a case within its permitted case scope. *Policy: `case.assignment.v1`; default: manual assignment, initially unassigned.* - **CASE-006 — Priority.** Each case has low, medium, or high priority and starts at medium. A member can change it, and its recorded reason says whether its current value came from a member or AI-005 suggestion. - **CASE-007 — Due time.** Every non-completed case stores a UTC due instant computed from configured IANA workspace timezone, weekly working schedule, and holiday dates, and is labelled due later, due today, or overdue in that timezone. A later schedule change affects only new calculations. *Policy: `case.due-time.v1`; default: four configured working hours from creation.* - **CASE-008 — Replies and notes.** Case activity may show prepared customer messages and internal notes. A note remains private under CONV-007, and a prepared customer message still requires JUDG-004 and ACT-013 before it is sent. - **CASE-009 — Waiting.** Moving a case to waiting records a reason and wake time. It returns to working within 60 seconds of wake or immediately on a non-automatic customer message, and each return produces exactly one operator alert under NOTIFY-002. - **CASE-010 — Explicit completion.** Approval and provider acceptance never complete a case. An executable-action case completes only after the authoritative provider reports that action succeeded and its required reviewed customer message is recorded sent. A documented no-action resolution may complete a case only when it has no pending, indeterminate, or succeeded action; a failed action remains visible and needs either replacement or the documented permitted no-action resolution. Inactivity and conversation close never complete a case. - **CASE-011 — Follow-up after completion.** A member can create a linked follow-up case after completion. No later customer message creates a follow-up automatically; previous decisions, actions, and receipts remain immutable. - **CASE-012 — Case merge.** A permitted member may merge two non-completed cases only when they belong to the same customer and have compatible visibility scope; a Tracker case cannot merge with a Customer or Back-office case. The member names a canonical case and records a reason. The losing case becomes a read-only pointer, retains its notes, evidence, decision versions, event history, originating conversation, and links, accepts no new proposal, decision, action, or case link, and cannot expose its private history through the canonical case. The merge emits `case.merged.v1` naming both cases, canonical case, member, time, and reason. Case merge is separate from CONV-010 and never erases a source conversation. - **CASE-013 — Views.** Members can list cases by primary queue, lifecycle state, channel, assignee, priority, due state, and tag, sorted by last activity or due time in pages of the size declared in seed.json limits. - **CASE-014 — Search.** Full-text search over customer names and contact points, message bodies, case subjects and identifiers, evidence labels, and receipt references returns authorised matching cases within 500ms. - **CASE-015 — Unread.** A case is unread for a member until that member opens it after the latest customer message in its conversation. Every authorised case view shows that member's unread count. - **CASE-016 — Escalation.** A permitted member can set or clear a durable escalation flag with reason. The flag routes the case to Escalated without changing lifecycle state, assignee, or due time, and alerts the members named by notification.routing.v1. - **CASE-017 — Tags.** A permitted member can add and remove named case tags. Tags are filterable under CASE-013, reportable under ANALYTICS-003, and included in an authorised operator export. - **CASE-018 — Additive conversation links.** A case retains its origin conversation and may receive additional audited related-conversation links. A link is additive: it does not merge conversations, customers, identities, notes, messages, or case histories, and it carries the member, reason, and time. - **CASE-019 — Customer case.** A Customer case is customer shared and reply capable. It has a stable short public case number; its public route exposes only customer-safe material authorised for that case. - **CASE-020 — Back-office case.** A Back-office case is private by default in 1.0. A later customer-exposure capability requires a new contract clause, release change, permissions model, and customer-safe disclosure rules. - **CASE-021 — Tracker privacy.** A Tracker case has no public number, public route, customer search result, customer export entry, or customer notification. No setting, policy, extension, import flag, edition, or role grant can make it customer shared. - **CASE-022 — Tracker aggregation and action boundary.** A Tracker may aggregate related conversations and linked cases for a widespread issue using CASE-018. It never merges customer identities and cannot itself authorise a customer send or provider action. Each customer-specific target has a separate linked Customer or Back-office case with its own origin, target, decision, approval, command, outcome, and receipt. - **CASE-023 — Category configuration.** A routing administrator can configure case states and attributes by case type. Category configuration cannot relax CASE-019, CASE-020, CASE-021, CASE-022, JUDG-004, or provider-outcome rules. ## Customers and contacts - **CUST-001 — Customer and visitor records.** An inbound message from a verified email contact links the unique customer that owns that contact, or creates one customer when no such verified association exists. A web-chat visitor without a verified contact remains an anonymous visitor record; obtaining a verified contact can link it to that customer. - **CUST-002 — Customer profile.** A customer holds name, verified contact points, preferred contact method, relationships, permitted notes, tags, enabled custom fields, conversations, cases, action outcomes, receipts, and audited activity. A permitted member can edit profile fields, and activity records each edit with actor, time, and before/after value. - **CUST-003 — Contact matching.** One verified case-insensitive email contact belongs to exactly one customer, and every inbound conversation from that verified contact links to that customer. A customer-entered unverified contact value neither merges customers nor authorises disclosure. - **CUST-004 — Signed web identity.** A host may pass a signed customer identity. An absent or invalid signature leaves the visitor anonymous and exposes no customer history; a valid identity links only the named customer. - **CUST-005 — Consequential identity basis.** A customer-specific decision records the verified contact, signed identity, or operator-recorded verification tying its target to the customer, including method and time. Approval refuses without this basis. - **CUST-006 — People, companies, and history.** A permitted member can view people, companies, and their relationships. A customer history lists that customer's conversations, cases, action outcomes, receipts, and activity in chronological order without changing primary-record ownership. - **CUST-007 — Customer merge.** A permitted member can merge two customers only after reviewing both identities and histories. The canonical customer receives every linked conversation, case, action outcome, receipt, and permitted profile record; the losing customer becomes an auditable pointer preserving source lineage and both identities. The merge never exposes Tracker content to a customer. - **CUST-008 — Customer block.** A permitted operator can block or unblock a customer. While blocked, new messages are preserved but create no alert, AI request, automatic state change, or case. - **CUST-009 — Verified contact points.** A contact becomes verified only through inbound mail, a valid signed identity, or its owner opening a one-time confirmation link. It records method, time, and actor; unverified contacts receive no case content, receipt link, transcript, or customer delivery. - **CUST-010 — Import and segments.** An operator can import and manage customers, companies, tags, and segments only through IMPORT-001 and declared contact rules; imports cannot infer customer identity from Tracker aggregation. ## Evidence and knowledge - **EVID-001 — Evidence records.** Each evidence record names type, source system, immutable source identifier, retrieval time, verification state, and requesting case. In every operator presentation card numbers, bank-account numbers, and provider secrets show only their last four characters where shown at all. - **EVID-002 — Source truth.** Provider data and uploaded originals remain distinguishable from AI extraction or summary. AI output alone never verifies evidence. - **EVID-003 — Collection failure.** Missing, not-found, or errored evidence is shown unavailable with reason and attempt time and is never replaced by generated content. Required unavailable evidence blocks a decision. - **EVID-004 — Decision snapshot evidence.** A decision snapshot records the customer identity basis, action target and parameters, evidence IDs and verification states, exact knowledge or policy revision and section, proposed customer text, preparer, and rationale reviewed. - **EVID-005 — Revision invalidation.** Changing cited evidence, knowledge, target, parameter, action, or customer message creates a new decision version and invalidates any pending approval of the superseded version. - **EVID-006 — Historical integrity.** Evidence and knowledge revisions cited by a decision remain readable and unchanged after live sources change; a receipt renders from cited versions, subject to DATA-002 anonymisation. - **EVID-007 — Evidence pack.** An authorised operator can export a case's permitted messages, evidence metadata and originals, decision versions, outcomes, and receipt as a portable archive without Tracker disclosure to a customer. - **EVID-008 — Required evidence.** Each declared executable operation names the verified evidence required before approval. *Policy: `evidence.requirements.v2`; default: the operation declaration's verified evidence and current identity basis, while no-action requires a documented reason.* - **KNOW-001 — Knowledge library.** Operators can create, revise, organise, archive, and search structured articles and guidance. A revision has draft, in-review, published, or outdated state and immutable history. - **KNOW-002 — Policy at event time.** An operational recommendation or decision selects the published knowledge or policy revision effective at the cited transaction or event time, or at case creation when no transaction/event exists, and freezes that exact revision and section into EVID-004 and ACT-010. - **KNOW-003 — Private material boundary.** Internal notes, customer messages, account data, security reports, and one-off concessions become reusable knowledge only through an operator-authored saved revision. - **KNOW-004 — Reply templates.** Operators can create, edit, retire, and insert named templates. Insertion fills a review editor and sends nothing. - **KNOW-005 — Public Help Center.** Published public articles may appear in a Help Center with customer-safe routes and revision history. It never exposes private notes, Back-office content, Tracker content, decision evidence, or drafts. - **KNOW-006 — Source hub.** An operator can declare a knowledge source and see enabled, ingesting, stale, failed, or disabled state with the source boundary and last retrieval. - **KNOW-007 — Content suggestions.** AI may prepare a knowledge-content suggestion for operator review. It is not published or used by an assistant until an operator saves and publishes a revision. - **KNOW-008 — Library health.** The library identifies stale or failed source material and published revisions needing review; it labels unavailable inputs rather than inventing freshness. ## AI preparation - **AI-001 — Requested preparation.** A member can request a summary, classification, extraction, recommendation, reply draft, or content suggestion. The result is labelled AI, linked to its model call, and neither sent nor acted on. - **AI-002 — Grounding.** Every AI output names the conversation, evidence, customer fields, and knowledge revisions it read. An uncited requested fact is returned as missing, not invented. - **AI-003 — Recommendation contents.** An actionable recommendation states the proposed operation, target, customer consequence, rationale, confidence, missing evidence, and editable customer text where a message may be needed. - **AI-004 — No AI authority.** AI cannot send a customer message, approve, execute, merge, complete, verify evidence, change a customer, change knowledge, or change a permission. - **AI-005 — Triage.** When `ai.provider.v1` is configured, within 10 seconds of each non-automatic customer message Beacon records exactly one of: a labelled intent, priority suggestion, and EVID-008 checklist; an explicit no-match that changes no case field; or the AI-008 failure record. A member reviews any suggested queue or priority before it changes work state. - **AI-006 — Mandatory review.** A case meeting a mandatory-review trigger is labelled Mandatory review and receives no recommendation until a member asks. On another case whose AI-005 intent names a resolution type, Beacon may prepare one only after required EVID-008 evidence is complete. Neither path lets AI act. *Policy: `ai.review-boundary.v1`; default: no CUST-005 identity basis, a customer request for a human, or an AI intent of security, legal, or account access; an override may add triggers but cannot remove these triggers or the JUDG-004 gate.* - **AI-007 — Instructions.** Drafts and recommendations follow buyer-authored instructions that never override evidence, policy, source boundary, approval, action, or privacy constraints. *Policy: `ai.instructions.v1`; default: answer concisely from cited case and knowledge sources only.* - **AI-008 — Provider failure.** With `ai.provider.v1` unconfigured, AI controls are visibly unavailable and triage is skipped. When a call times out or fails, the member sees the recorded error, the case stays usable, no decision is created, and no other case transition happens. - **AI-009 — Cost.** Every AI call records provider, model, feature, input and output tokens, latency, and estimated cost, and operators can inspect totals by day and feature. - **AI-010 — Proposal boundary.** A recommendation becomes a decision only when a signed-in member saves a reviewed immutable ACT-010 decision snapshot. A recommendation identifier is refused wherever a decision version is required, and accepting it records the member who accepted it. - **AI-011 — Untrusted sources.** Customer messages, attachments, provider fields, retrieved evidence, and knowledge content are data, never instructions. They cannot widen source access, action permissions, or fields sent through `ai.provider.v1`. - **AI-012 — Customer language.** A customer record stores the language of their messages, detected on first contact and editable by a member. A member sees a labelled translation of a message outside the configured workspace language before deciding; an AI-drafted customer message is written in the customer language. Without `ai.provider.v1` the language is member-set and no translation is shown. - **AI-013 — Test set and review.** Operators can add manual questions, generated questions, or imported CSV questions to an AI test set, and review source, expected answer, rating, and notes before any deployment preparation. - **AI-014 — Deployment preparation.** Operators can prepare an AI deployment audience, channel, escalation path, and version for review. Preparation is disabled for live sending or external action until JUDG-004, ACT-011, and channel approvals are satisfied. - **AI-015 — Performance analysis.** Operators can inspect labelled AI preparation performance and zero-involvement conversations with source and date range; no success-looking chart proves delivery or correctness. - **AI-016 — Usage guard.** A workspace can set usage alerts and a hard limit. At its limit, AI preparation stops and conversations route to permitted teammates; no existing customer message or provider outcome is fabricated. - **AI-017 — Workflow preparation.** Operators can prepare an internal reviewable workflow. It cannot activate an autonomous customer send, external provider mutation, or an extension bypass of JUDG-004. - **AI-018 — Deferred Fin navigation.** Fin Tasks, Fin Suggestions, and Simple automations are known visible navigation labels whose working workflows are unobserved. They are not 1.0 capability promises and do not appear as active edition functionality. ## Judgment and approval - **JUDG-001 — Eligible recommendation.** A case may have one current recommendation naming a permitted operation or escalation, rationale, customer consequence, risk, confidence, and cited facts. A recommendation is eligible only with its declared evidence and published knowledge. - **JUDG-002 — Evidence provenance.** Every recommendation fact and citation preserves source identifier, captured value, source version, and retrieval time, viewable by the reviewer. - **JUDG-003 — Published policy.** An executable recommendation names the exact published knowledge revision and section it applies. - **JUDG-004 — Human gate.** Beacon sends no customer message until a signed-in member holding either the conversation-send grant for a CONV-014 conversation-scoped send, whether or not that conversation has linked cases, or the case-type decide grant for a case decision approves the reviewed send or submits a manual resolution. Beacon makes no external-provider mutation until a signed-in member holding the case-type decide grant approves the reviewed case decision or submits a manual resolution. No policy, setting, extension, importer, workflow, or edition removes either requirement. - **JUDG-005 — Manual resolution.** A signed-in eligible member can select a different permitted operation, no-action resolution, or escalation, record an internal reason, and submit a reviewed manual decision. The original recommendation and evidence remain beside it. - **JUDG-006 — Freshness gate.** If any reviewed decision field, evidence, identity basis, knowledge revision, target, or provider preflight condition changes before approval, approval is refused and the affected fields are named. - **JUDG-007 — Insufficient evidence.** A case with missing, conflicting, or ineligible evidence shows its reason and offers only investigation, escalation, or a documented no-action resolution. It presents no executable AI recommendation. - **JUDG-008 — AI failure boundary.** AI failure retains manual investigation and existing approved work but produces no silent substitute evidence, classification, recommendation, or customer send. - **JUDG-009 — Instruction boundary.** Buyer guidance can alter preparation wording or permitted source selection only through AI-007; it cannot relax JUDG-002, JUDG-004, JUDG-006, or EVID-008. - **JUDG-010 — Reversibility.** A recommendation or manual decision states whether its declared provider operation is reversible and names the reversal operation where one exists. An irreversible operation is labelled wherever it can be approved. - **JUDG-011 — Named review.** The review surface shows the case type, customer identity basis, action target, evidence, knowledge, proposed text, decision version, and approving member so a reviewer can reject or return it before action. - **APPR-001 — Approval request.** A request is created only for a stored current decision version meeting EVID-008 and CUST-005. It names the case, target, operation, requester, reviewers, and requested time. - **APPR-002 — Approval queue.** Approval requests are listed by case lifecycle state—awaiting_approval, returned, declined, executing, action_failed, action_indeterminate, awaiting_message, notification_failed, or completed—with due state and assignee; every row links to the exact decision version reviewed. - **APPR-003 — Review.** The eligible reviewer sees the complete EVID-004 snapshot, including exact policy section, and can open every cited source before deciding. The surface identifies preparer, reviewer, and decision version. - **APPR-004 — Decisions.** An eligible reviewer can approve, return for changes, or decline. Return and decline require a reason, and every decision records the deciding member and time. - **APPR-005 — Return.** Returning a decision moves the case to returned, preserves the reviewed snapshot and reason, and requires a new decision version before approval can be requested again. - **APPR-006 — Decline.** Declining a decision preserves the reviewed snapshot and reason, moves the case to declined, sends no provider command or customer message, and leaves the case for a member to re-propose or complete only under CASE-010. - **APPR-007 — Single decision.** One decision version accepts one terminal decision. A repeated click or request returns the stored decision and creates no further action. - **APPR-008 — Approval command.** Once APPR-009 succeeds for an executable provider operation, approval atomically stores the decision, moves the case to executing, and creates exactly one durable provider command for that decision. A documented no-action decision atomically stores its decision and creates no provider command. Neither is provider execution, customer delivery, or case completion. - **APPR-009 — Approval preconditions.** Immediately before approval Beacon refetches and revalidates case state, current decision version, case-type decide grant, policy eligibility, CUST-005 identity basis, and cited evidence versions and verification states. An executable provider operation requires ACT-009 eligibility and ACT-011 provider preflight. A documented no-action requires CASE-010 guards and EVID-008 evidence, but no provider state or provider preflight. An unavailable required authoritative state or mismatch returns a conflict, audits the rejected attempt, and stores neither decision nor command. ## Actions and provider truth - **ACT-001 — Action adapter.** A declared external operation executes through `operations.provider.v1` with target, parameters, reason, and Beacon idempotency key. A concrete operation is executable only when ACT-009 and ACT-011 admit it. - **ACT-002 — Idempotency.** Repeated approval clicks, queue retries, Worker restarts, and duplicate provider webhooks refer to the same durable action and never issue a second logical action. - **ACT-003 — Outcome states.** An action is in exactly one of pending, succeeded, failed, or indeterminate and records redacted provider request and outcome fields, provider event IDs, and reconciliation attempts. - **ACT-004 — Indeterminate result.** A timeout, lost connection, or ambiguous provider response makes the action indeterminate and blocks further mutation on its target until ACT-005 establishes whether the original command took effect. - **ACT-005 — Reconciliation.** Provider events and scheduled status checks update an action idempotently. The scheduled check runs at least every 15 minutes on a pending or indeterminate action for up to seven days; a late authoritative success or failure updates that same action and case. An action unresolved after seven days becomes indeterminate if pending, stops being checked, and alerts the responsible member and assignee for manual reconciliation. - **ACT-006 — Completion.** Approval and provider acceptance do not complete a case. An executable-action case reaches completed only after operations.provider.v1 reports the action succeeded and its required reviewed customer message is recorded sent. Failed or indeterminate actions cannot complete a case; documented no-action completion remains governed by CASE-010. - **ACT-007 — Failed action.** A definitively failed action retains its decision and can be replaced only by a new decision that records it and carries a new idempotency key. An indeterminate action blocks replacement until reconciled. - **ACT-008 — Provider claims.** Beacon shows an arrival estimate, destination confirmation, external reference, or outcome detail only when the authoritative provider supplied it, and labels unavailable information as pending or unknown. - **ACT-009 — Action eligibility.** An operation must match EVID-008 required evidence, current identity basis, target, parameter constraints, and authoritative provider conditions; a change refuses approval or command submission. - **ACT-010 — Immutable decision snapshot.** A submitted decision snapshots exactly the case, customer identity basis, actor, operation, parameters, action target, customer consequence, evidence IDs and states, exact knowledge or policy revision and section, and submission time. It cannot be edited or cancelled. - **ACT-011 — Immediate provider preflight.** Immediately before command submission, Beacon reads current authoritative provider state and refuses unless target, customer identity, operation, parameters, and declared conflict conditions still match the decision. The command carries the current provider version or equivalent precondition. - **ACT-012 — Execution progress.** A decision shows validation, provider execution, outcome recording, and customer-draft preparation, with start and completion times for each completed step. - **ACT-013 — Customer-message preparation and send.** A confirmed or documented outcome can prepare customer text stating only what authoritative outcome permits and labelling uncertainty. It never sends itself. A signed-in member reviews and approves or manually resolves the send under JUDG-004; only then may CHAN-005 or CHAN-007 deliver it. - **ACT-014 — One in-flight target.** At most one decision for a case and action target is validating or executing at a time. A second approval returns the existing state rather than starting another attempt. - **ACT-015 — Conditional mutation.** An operation whose adapter cannot provide a current-version or equivalent conditional mutation is never executable; it is offered only as escalation or manual investigation. - **ACT-016 — Execution pause.** An authorised member can pause external execution for the deployment. Intake, review, and approvals remain available, but no provider command is sent; resumption revalidates each command under ACT-011. - **ACT-017 — Provider outage.** When an operations provider cannot read or preflight, Beacon names the outage, refuses provider-action approval, and preserves intake, manual investigation, and no-action resolution. It never queues an unpreflighted mutation as if ready. - **ACT-018 — Reversal.** A provider-declared reversible action is reversed only by a new case and new decision naming the original decision. Original snapshots and receipts remain immutable and linked. - **ACT-019 — Declared operation boundary.** An executable operation declares its provider adapter, target shape, identity precondition, required evidence, reversibility, and receipt shape. Beacon does not invent a generic provider adapter or operation from a UI field. ## Receipts and notifications - **RCPT-001 — Receipt creation.** A receipt is created only when CASE-010 permits completed resolution. It is immutable and holds customer and public-case references where applicable, completion basis, acting member and time, exact evidence and knowledge/policy IDs, declared action parameters including amount and currency when financial, action target, authoritative outcome, required customer-message body and delivery state, and chronological activity. A pending or failed delivery remains an operational action view, not a completed-resolution receipt; a documented no-action receipt names its reason. - **RCPT-002 — Action record before completion.** Before CASE-010 completion an authorised member sees an action or outcome-progress record labelled approved, executing, pending, succeeded, failed, indeterminate, or reconciled as applicable. It is not a completed-resolution receipt. A completed receipt is created only under RCPT-001 and may receive append-only amendments under RCPT-004; approval, submission, and provider acceptance are never success. - **RCPT-003 — Customer receipt access.** An authorised member can view and download a receipt from its case and the customer history. A Customer-case customer receives one signed link to one redacted receipt that expires 30 days after issue and then returns an expired page with no receipt content. The receipt excludes internal notes, Back-office material, Tracker material, private evidence, and operator rationale. - **RCPT-004 — Amendments.** Later events never rewrite a receipt snapshot. A late provider or delivery event creates an append-only amendment presented beside the original. - **RCPT-005 — Per-target ownership.** A receipt belongs to one case and one declared action target. Tracker aggregation cannot create a group receipt or allow one decision receipt to cover unstated customers or targets. - **NOTIFY-001 — Customer notification truth.** A case outcome notification is sent only under JUDG-004 and ACT-013 and states only the authoritative or documented outcome permitted for its case and target. An ordinary conversation-scoped customer send is sent only under JUDG-004 and CONV-014, whether or not its conversation has linked cases; it is a reviewed conversation delivery, not a case outcome, action, command, or receipt. - **NOTIFY-002 — Operator routing.** Case creation, assignment, escalation, approval request, return, failure, indeterminate outcome, and delivery failure notify authorised members. *Policy: `notification.routing.v1`; default: conversation or case assignee, otherwise approving member, otherwise eligible operators.* - **NOTIFY-003 — Quiet hours.** Configured quiet hours hold routine email alerts until the next working period while failure and indeterminate-outcome alerts send immediately. In-app alerts are not held. - **NOTIFY-004 — Coalescing.** At most one unread customer-reply alert and one unread approval-needed alert are outstanding per member per case; later matching events update it. - **NOTIFY-005 — Delivery status.** Every operator alert and customer notification records provider acceptance, delivery where confirmed, bounce, retry, and terminal failure without changing a confirmed provider outcome. - **NOTIFY-006 — Customer-message failure.** A failed required customer message moves the case to notification_failed, preserves the action outcome, and alerts the responsible operator until reviewed delivery is resolved. - **NOTIFY-007 — No loops.** Operator notifications, receipt links, transcripts, and optional customer notices use a no-reply address distinct from the support address. Mail to it creates no conversation, case, alert, or AI request. ## Reports and setup - **ANALYTICS-001 — Event-derived metrics.** Analytics derive from immutable conversation, case, decision, action, notification, and feedback events; editing a live record never rewrites an earlier reporting event. - **ANALYTICS-002 — Conversation and outcome definitions.** Reports distinguish first response, conversation volume, customer message delivery, decisions, approvals, provider-confirmed success, failure, indeterminate outcome, reconciliation, and no-action resolution. - **ANALYTICS-003 — Filters and drill-down.** A report names its date range, workspace timezone, completion watermark, and filters. Each aggregate drills into the authorised source conversations, cases, or actions it counted. - **ANALYTICS-004 — Exports and unavailable metrics.** An operator can export authorised report rows. A zero denominator or missing input is shown unavailable with reason, never fabricated as zero. - **ANALYTICS-005 — Custom charts.** Operators can prepare saved report charts from declared event dimensions and measures. A chart does not expose Tracker data to a customer or change operational truth. - **ANALYTICS-006 — Conversation topics.** Operators can review conversation-topic analysis with its source range and model provenance. AI-derived topics remain analysis, not verified customer facts. - **SETUP-001 — Guided setup.** A workspace can present a setup path for sign-in, teammate grants, inboxes, verified channels, widget origins, knowledge, provider adapters, and deployment checks. It labels unconfigured steps rather than claiming readiness. ## Data and import - **DATA-001 — Portable export contents.** An authorised operator export contains every permitted customer, visitor, conversation, message, case, tag, evidence, knowledge revision, decision, approval, action, provider event, receipt, notification, setting, and audit entry, plus permitted attachment originals. - **DATA-002 — Retention after erasure, superseding BASE-DATA-003.** Erasing a customer removes their conversations, messages, attachments, evidence originals, and profile under the baseline five-minute cascade, and retains every approval, action, provider event, and receipt with customer reference, message bodies, and contact points anonymised because the business must prove completed operations. The erasure confirmation names what remains and why. The rest of BASE-DATA-003, including its cascade and confirmation, applies unchanged. - **IMPORT-001 — Intercom export importer.** Beacon has one 1.0 importer: Intercom export import. It reads a real Intercom export and declares supported entities, links, attachment treatment, source-ID/timestamp/visibility/history preservation, deterministic idempotency, rejected-record diagnostics, and truthful unsupported-data handling before it imports. It never activates a live Fin reply, workflow, outbound send, provider mutation, public sharing, or Tracker disclosure from source data. Real export proof and implementation are Stage 2 work. ## Deferred and out of scope The following matrix dispositions are explicit and are not capability claims: SMS and WhatsApp adapters are deferred; in-app announcements (banners, tooltips, posts, news), mobile push and carousel, product tours and checklists, and surveys are out of 1.0; Fin Tasks, Fin Suggestions, and Simple automations have observed navigation presence but unobserved workflows and are deferred; trial and vendor-promotion furniture is out. Help Scout is deferred: there is no Help Scout importer, replacement claim, or evidence claim. Beacon does not ship multiple workspaces or tenants, a native mobile operator app, live autonomous AI replies, customer-message automation, external-provider automation, a generic workflow or runtime plugin system, an undocumented external system-of-record migration, or a claim that this Stage 1 contract is already a 1.0 runtime.