@ego-z/contracts 0.14.4 → 0.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.14.4",
+  "version": "0.15.3",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {

package/src/draft-conv.d.ts

@@ -0,0 +1,373 @@
+/**
+ * @ego-z/contracts — `POST /egoz/conversations/draft` wire types.
+ *
+ * The GHOSTED CONVERSATION START. When a tenant surface opens a new chat
+ * panel, it calls this before the user has typed anything. EgoZ mints a
+ * conversation id, stores the caller's init context against it as a draft,
+ * and returns quick suggested prompts — so the panel opens with a real id
+ * and something to click, rather than acquiring both mid-stream on the first
+ * message.
+ *
+ * No LLM turn is billed. Nothing is persisted as a user message: the init
+ * context is rendered into the system prompt as context, never as something
+ * the model answers.
+ *
+ * ── Two ids, and only one of them is an identity ─────────────────────────
+ *
+ * `conversationId` is EgoZ-minted and canonical — the only id a follow-up
+ * `/ask` ever carries. `draftKey` is a caller-generated dedupe token for one
+ * chat panel. They are deliberately separate: the thing that needs
+ * uniqueness (a panel's attempt to start a draft) is not the thing that
+ * needs identity (a conversation), and conflating them would change which id
+ * is canonical for every existing caller.
+ *
+ * ── Evolution ────────────────────────────────────────────────────────────
+ *
+ * Additive only. Every `initContext` field is optional, so a caller that
+ * hasn't implemented a field yet degrades one feature rather than failing a
+ * request. Unknown fields are TOLERATED, not rejected — but they are also
+ * not forwarded: the server keeps only what it models, because everything
+ * here is rendered into a system prompt and arbitrary caller JSON reaching
+ * that position is an injection surface, not a convenience. Callers with
+ * something unmodelled to say use `notes`.
+ */
+
+import type { ThreadStatus } from './thread';
+
+// ============================================================================
+// Init context — the snapshot that accompanies a start
+// ============================================================================
+
+/** Resolved colour scheme. Never a preference — see `InitContextUi.theme`. */
+export type InitContextTheme = 'light' | 'dark';
+
+/** Viewport class. Deliberately not "device" — see `InitContextUi.viewport`. */
+export type InitContextViewport = 'mobile' | 'desktop';
+
+/**
+ * Which population a user belongs to — see `InitContextUser.audience`.
+ *
+ * - `'operator'` — runs the tenant's product. Admins, owners, staff,
+ *   specialists, back-office users: whatever the deployment calls them.
+ * - `'customer'` — uses it. End users, buyers, patients, guests.
+ *
+ * Two values, not a list of job titles: the distinction that changes how an
+ * agent should speak is "do you run this, or do you use it". Finer-grained
+ * distinctions belong in `roles`, which is free-form precisely because that
+ * vocabulary is the deployment's, not EgoZ's.
+ */
+export type InitContextAudience = 'operator' | 'customer';
+
+/** One open window in the caller's UI. */
+export interface InitContextOpenWindow {
+    /** Epoch millis the window was opened. */
+    openedAt?: number;
+    /**
+     * Human-readable window label, e.g. `"Blue Hoodie"`. Safe to render
+     * verbatim — unlike the window KEY, which embeds entity ids and is
+     * rendered only for the focused window.
+     */
+    title?: string;
+    isFocused?: boolean;
+}
+
+/** One visited tab. `visitedAt` gives suggestion ranking a recency tiebreak. */
+export interface InitContextVisitedTab {
+    /** Epoch millis the tab was last visited. */
+    visitedAt?: number;
+    isCurrent?: boolean;
+}
+
+/**
+ * What the user is looking at.
+ *
+ * The first four fields are structurally identical to the AppNa console's
+ * `UserContext`, so a caller that already models an OS-style window system
+ * passes its context straight through with no mapper. They are declared here
+ * as EgoZ's own type rather than imported: EgoZ serves callers that are not
+ * window systems, and a public contract that mirrors one client's internal
+ * type makes every refactor of that client a breaking change here.
+ *
+ * RANKING USES FOCUS, NOT THE SET. "Has Orders open" is weak signal; "is
+ * looking at a product detail" is strong. `openWindows` is a secondary
+ * signal and `visitedTabs[].visitedAt` a tiebreak.
+ */
+export interface InitContextUi {
+    /** Coarse screen the user is on, e.g. `"ecommerce"`, `"orders"`. */
+    currentRouteId?: string | null;
+    /** Key of the focused window, e.g. `"ecommerce:productDetail:abc"`. */
+    focusedWindowId?: string | null;
+    openWindows?: Record<string, InitContextOpenWindow>;
+    visitedTabs?: Record<string, InitContextVisitedTab>;
+    /**
+     * The RESOLVED colour scheme — never a preference. A caller whose stored
+     * setting is "system" MUST resolve it against `prefers-color-scheme`
+     * before sending: `'system'` is a state EgoZ cannot evaluate and has
+     * nothing useful to say about, and it would be the value for a large
+     * share of users.
+     */
+    theme?: InitContextTheme | null;
+    /**
+     * Viewport class — NOT a device. Callers derive it from a width
+     * breakpoint, so a narrowed desktop browser window reports `'mobile'`.
+     * Named for what it measures on purpose: `device` would invite the agent
+     * to say "since you're on your phone…" to someone who dragged their
+     * window narrow. A real device signal (touch capability, UA) would be a
+     * separate field with a separate source.
+     */
+    viewport?: InitContextViewport | null;
+}
+
+/**
+ * Who the user is.
+ *
+ * `name` is nullable: a phone-only signup genuinely has none, and the
+ * greeting has a no-name path rather than producing "Hello, null".
+ *
+ * ── `roles` is a SET, and it is ADDITIVE-ONLY ────────────────────────────
+ *
+ * A role gates which actions the agent offers, which makes a client-asserted
+ * role a client-asserted permission. It MUST be resolved by whoever
+ * authenticated the user; a gateway fills it from the verified session and
+ * ignores whatever the browser sent. The vocabulary belongs to the caller's
+ * product, so entries are free-form strings.
+ *
+ * It is an ARRAY, not a single value, because the underlying fact is a set
+ * and collapsing a set needs a precedence rule — a precedence rule absent
+ * from the contract is one each implementer invents privately, and an owner
+ * who also takes appointments then never sees the specialist suggestions.
+ *
+ * It may only ever WIDEN what the agent offers — add to the capability
+ * summary, boost ranking — and may never narrow either. The reason is a
+ * property of the source: on a permissions node where present means true
+ * and ABSENT MEANS UNKNOWN, `['Specialist']` does not mean "not an owner",
+ * it means "specialist is true and the rest is unknown". Every inference of
+ * the form *only a specialist, so hide X* is unsound on that data.
+ *
+ * The asymmetry also matters because the failure is invisible: a wrongly
+ * SHOWN suggestion gets reported, a wrongly HIDDEN one never does — the user
+ * just sees a less useful assistant and assumes that's what it is. Hard
+ * filtering belongs to `tenant.features`, which genuinely can say no.
+ *
+ * There is no `id` field: the end user is already identified at request
+ * level by `externalUserId`. One id, one place.
+ */
+export interface InitContextUser {
+    name?: string | null;
+    roles?: string[];
+    /**
+     * WHICH POPULATION this person belongs to — the people who RUN the
+     * tenant's product, or the people who USE it.
+     *
+     * Every EgoZ deployment serves one or both, and the agent should not
+     * speak to them the same way: an operator wants "I can help you manage
+     * your catalogue", a customer wants "I can help you track your order".
+     * Offering the first to the second is wrong in the opening sentence, and
+     * it reads as the product not knowing who it is talking to.
+     *
+     * Deliberately NOT a boolean, and deliberately not named after any one
+     * product's org chart. A boolean forces every deployment to express its
+     * populations as "staff / not-staff", which is one integration's
+     * vocabulary; and a boolean has no way to say "I did not resolve this",
+     * so absent and false become indistinguishable at exactly the moment the
+     * difference matters.
+     *
+     * ── The one signal allowed to NARROW ─────────────────────────────────
+     *
+     * `roles` may only widen, because its source generally cannot tell
+     * "false" from "not recorded". This field is different: it is the
+     * caller's own answer to a question they authoritatively know, so it may
+     * gate — it is the only field here that can.
+     *
+     * ── ABSENT MEANS `'customer'`. Fail closed. ──────────────────────────
+     *
+     * Read a missing value as the LESS privileged population, never as
+     * "unknown, assume operator". Callers that serve both populations often
+     * cannot distinguish them on every path, and the failure directions are
+     * not symmetric: greeting an operator as a customer is a smaller,
+     * self-correcting mistake than offering a customer administrative
+     * actions they will then fail to perform.
+     */
+    audience?: InitContextAudience;
+}
+
+/**
+ * Language.
+ *
+ * TWO DIFFERENT FACTS ABOUT TWO DIFFERENT SUBJECTS — the distinction is
+ * load-bearing and was got wrong once already:
+ *
+ * - `selected` is **which language this person reads**. It is the only input
+ *   to which language EgoZ replies in. The response echoes the RESOLVED
+ *   value, so the caller and EgoZ cannot silently disagree about it.
+ * - `supported` is **which languages the tenant's CONTENT exists in** — a
+ *   catalogue of the store's translations, not a list of languages the user
+ *   understands. It is NEVER consulted when resolving the reply language:
+ *   doing so gives a French-reading admin at an Arabic-only store Arabic
+ *   chips, which is the resolver faithfully answering the wrong question.
+ *
+ * `supported` is still worth sending — it belongs in the prompt, where it
+ * makes "translate this product into Hebrew" a sensible suggestion for one
+ * tenant and a dead end for another.
+ */
+export interface InitContextLocale {
+    /** The language the USER reads, e.g. `"ar"`. Drives the reply language. */
+    selected?: string | null;
+    /**
+     * The languages the TENANT'S CONTENT exists in, e.g. `["en","ar","he"]`.
+     * Context for the agent; never used to resolve the reply language.
+     */
+    supported?: string[];
+}
+
+/**
+ * The END TENANT this conversation belongs to.
+ *
+ * NOT necessarily the EgoZ tenant. On a gateway integration one EgoZ project
+ * fronts many of the gateway's tenants, so EgoZ's own tenant record
+ * describes the DEPLOYMENT and knows nothing about tenant "ABC". Which side
+ * is authoritative is declared once per EgoZ tenant (`tenantScope`), not
+ * inferred per request.
+ *
+ * `features` is the highest-value field here for suggestion quality: a
+ * per-tenant flag set EgoZ has no way to see. Without it the ranker either
+ * offers an action the tenant has switched off, or falls back to generic
+ * chips — the exact failure the ranking exists to avoid.
+ */
+export interface InitContextTenant {
+    name?: string | null;
+    description?: string | null;
+    category?: string | null;
+    /** Enabled-feature flags, e.g. `{ products: true, booking: false }`. */
+    features?: Record<string, boolean>;
+}
+
+/**
+ * The full init context. Every field optional — see the file header on
+ * additive evolution.
+ */
+export interface InitContext {
+    user?: InitContextUser;
+    locale?: InitContextLocale;
+    ui?: InitContextUi;
+    tenant?: InitContextTenant;
+    /** Anything the contract doesn't model yet. Rendered as untrusted data. */
+    notes?: string | null;
+    /**
+     * Epoch millis the caller took the snapshot. Optional; EgoZ stamps it on
+     * arrival when absent.
+     *
+     * It governs how long the `ui` half may still be rendered into a prompt,
+     * which is a SHORTER clock than the draft's own lifetime. A draft resumed
+     * after lunch is still the user's conversation, but "you have the
+     * Products window open" is by then a confident claim about a screen they
+     * closed — so past the snapshot window the UI half is dropped while
+     * `user` / `locale` / `tenant` still render.
+     */
+    capturedAt?: number;
+}
+
+// ============================================================================
+// Request / response
+// ============================================================================
+
+/** Body of `POST /egoz/conversations/draft`. */
+export interface StartDraftRequestBody {
+    /**
+     * Idempotency token for ONE chat panel — opaque, caller-generated, stable
+     * across remounts of that panel and fresh only for a genuinely new one.
+     * A good source is the panel's own window key plus a per-open nonce.
+     *
+     * Repeating a call with the same key refreshes that draft's init context
+     * and returns the SAME `conversationId` rather than minting another row.
+     * Callers SHOULD send one: a double-mounting panel that sends none leaks
+     * an orphan draft per mount.
+     *
+     * It is NOT a thread id and can never be used as one — its uniqueness
+     * index covers drafts only, and promotion drops it.
+     */
+    draftKey?: string;
+    /**
+     * Consumer-supplied conversation id, for callers that already mint their
+     * own (Phase 6). Unrelated to idempotency — that is `draftKey`'s job.
+     */
+    externalThreadId?: string;
+    /** The end user this conversation is for, as the caller identifies them. */
+    externalUserId?: string;
+    initContext?: InitContext;
+    /**
+     * The END TENANT this conversation belongs to, in the caller's own id
+     * space — required on a `gateway` integration, meaningless on a
+     * dedicated one.
+     *
+     * ON THE WIRE, not derived from request metadata: it is a scoping key,
+     * and a scoping key inferred from a caller-specific metadata field would
+     * make EgoZ's privacy boundary depend on one integration's vocabulary.
+     * The next gateway would either have to adopt that field name or earn a
+     * second branch.
+     *
+     * Without it, `(tenantId, externalUserId)` spans every one of the
+     * gateway's tenants the user belongs to — see `TenantScope`.
+     */
+    externalTenantId?: string;
+}
+
+/**
+ * Where a suggested prompt came from. Surfaced because the two have
+ * different quality and latency characteristics, and a caller measuring chip
+ * performance needs to tell an instant catalog hit from a model-generated
+ * fallback rather than averaging them together.
+ */
+export type SuggestedPromptSource = 'template' | 'llm';
+
+/** One suggested prompt chip, ready to render. */
+export interface SuggestedPromptWire {
+    /** Stable catalog id — for the caller's own analytics, not for display. */
+    id: string;
+    /** The prompt text, already in the resolved locale. */
+    text: string;
+    source: SuggestedPromptSource;
+}
+
+/** `data` payload of a successful `POST /egoz/conversations/draft`. */
+export interface StartDraftResponseData {
+    /**
+     * The canonical conversation id. This is what a follow-up `/ask` carries
+     * as `threadId`. A turn carrying it MUST come back with the same id —
+     * EgoZ never mints a replacement for a supplied id, and a lapsed draft
+     * fails with `DraftExpired` rather than quietly becoming a new
+     * conversation.
+     */
+    conversationId: string;
+    /** Always `'draft'` on a successful start; present so callers can assert. */
+    status: ThreadStatus;
+    /**
+     * ISO 8601. When the conversation id stops resolving — the row TTL.
+     *
+     * One of TWO CLOCKS, deliberately not collapsed into one number: this
+     * one governs how long the caller may still resume the conversation.
+     */
+    expiresAt: string;
+    /**
+     * ISO 8601, and much sooner than `expiresAt`. When the `ui` half of the
+     * init context stops being rendered into the prompt.
+     *
+     * The second clock. A draft resumed after lunch is still the user's
+     * conversation, but "you have the Products window open" is by then a
+     * confident claim about a screen they closed. Past this instant the UI
+     * half is dropped while `user` / `locale` / `tenant` keep rendering —
+     * those don't go stale.
+     */
+    contextExpiresAt: string;
+    /**
+     * Quick prompts for the panel to render, in `locale`. May be empty when
+     * nothing in the catalog fits and the fallback produced nothing — an
+     * empty list is a normal outcome, not an error.
+     */
+    suggestedPrompts: SuggestedPromptWire[];
+    /**
+     * The RESOLVED language — what EgoZ actually used — not the requested
+     * one. Render the chips in this.
+     */
+    locale: string;
+}

package/src/index.d.ts

@@ -53,8 +53,17 @@
  *   - `thread.d.ts`   — `ThreadWire`, `MessageWire`,
  *                        `ThreadWithStatsWire`, `ThreadWithMessagesWire`,
  *                        `ToolCallWire`, list / get response data,
- *                        vocabularies (`MessageRole`,
+ *                        vocabularies (`MessageRole`, `ThreadStatus`,
  *                        `MessageFailureReason`).
+ *   - `draft-conv.d.ts` — the ghosted conversation start:
+ *                        `InitContext` (+ `InitContextUser`,
+ *                        `InitContextLocale`, `InitContextUi`,
+ *                        `InitContextTenant`, `InitContextOpenWindow`,
+ *                        `InitContextVisitedTab`),
+ *                        `StartDraftRequestBody`, `StartDraftResponseData`,
+ *                        `SuggestedPromptWire`, vocabularies
+ *                        (`InitContextTheme`, `InitContextViewport`,
+ *                        `InitContextAudience`).
  *   - `personality.d.ts` — Both surfaces share this file. User-level:
  *                        `PersonalityProfileWire`, `PresetDefinitionWire`,
  *                        create / update bodies, `ActivePersonalityWire`.
@@ -89,6 +98,7 @@ export * from './mcp-token';
 export * from './mcp-connection';
 export * from './tenant';
 export * from './thread';
+export * from './draft-conv';
 export * from './personality';
 export * from './user-memory';
 export * from './search';

package/src/stream.d.ts

@@ -17,11 +17,14 @@ import type { Intent, TokenUsage } from './envelope';
  * Discriminated union of every event the streaming `/ask` endpoint emits.
  *
  * Notes on subset behaviour:
+ *   - `start` is always the FIRST frame, in every mode including
+ *     `'minimal'`. It carries the conversation id.
  *   - `stream: 'minimal'` requests omit `rag.*` and `tool.*` events.
  *   - `done` is always the terminal success frame.
  *   - `error` may appear at any point and is also terminal.
  */
 export type AskStreamEvent =
+    | AskStreamStartEvent
     | AskStreamIntentEvent
     | AskStreamRagSearchingEvent
     | AskStreamRagRetrievedEvent
@@ -34,6 +37,51 @@ export type AskStreamEvent =
     | AskStreamDoneEvent
     | AskStreamErrorEvent;
 
+/**
+ * The opening frame — emitted before any work begins, on every stream.
+ *
+ * ── Why the id cannot wait for `done` ────────────────────────────────────
+ *
+ * The conversation id is known the moment the thread is resolved, which is
+ * before the first token. Withholding it until the terminal frame forces
+ * every downstream consumer to either buffer the whole turn or guess, and
+ * guessing is what silently broke consumers that select a thread id on each
+ * event: they read `undefined` on every frame until the last one, so the
+ * selection simply never happened and nothing errored.
+ *
+ * A consumer that renders a transcript needs to know WHICH conversation it
+ * is rendering while the tokens are arriving, not after.
+ *
+ * ── Why a distinct event rather than a field on every frame ──────────────
+ *
+ * Repeating the id on `delta` would put it on the highest-frequency frame in
+ * the protocol for a value that never changes within a stream. One frame at
+ * the start says it once, and says it at the only moment a consumer needs to
+ * act on it: before anything is rendered.
+ *
+ * ADDITIVE. Consumers that don't know this variant ignore it — the same way
+ * they already ignore any event type they don't handle — and keep reading
+ * the id off `done` as before.
+ */
+export interface AskStreamStartEvent {
+    type: 'start';
+    /**
+     * The canonical conversation id, EgoZ-minted. Identical to the
+     * `threadId` that will arrive on `done`; a turn NEVER changes id
+     * mid-stream, so a consumer can commit to this value immediately.
+     */
+    threadId: string;
+    /** Echo of the supplied `externalThreadId`, when one was sent. */
+    externalThreadId?: string;
+    /**
+     * Whether this turn PROMOTED a ghosted draft — i.e. it is the first real
+     * message in a conversation that already had an id. Lets a consumer tell
+     * "this id is new to me" from "this id was pre-seeded at chat-open", which
+     * are different UI states even though both are a first turn.
+     */
+    promotedFromDraft?: boolean;
+}
+
 export interface AskStreamIntentEvent {
     type: 'intent';
     intent: Intent;

package/src/tenant.d.ts

@@ -123,6 +123,27 @@ export type TenantIndustry =
  * not a goal — net change would be breaking, with zero behavioural
  * value.
  */
+/**
+ * Whether an EgoZ project serves ONE customer or fronts MANY of a caller's
+ * own tenants. Mirrors the `egoz_tenants.tenant_scope` CHECK (migration 055).
+ *
+ * This is a fact about the INTEGRATION, declared once, not something inferred
+ * per request — inferring it from a caller-specific field would bake one
+ * integration's vocabulary into EgoZ's core scoping logic.
+ *
+ * - `'dedicated'` (default) — one project, one customer. `(tenantId,
+ *   externalUserId)` is a privacy boundary, which is what every per-end-user
+ *   feature assumes.
+ * - `'gateway'` — one project fronts many of the caller's tenants, and the
+ *   real tenant travels inside each request. **`(tenantId, externalUserId)`
+ *   is NOT a privacy boundary here**: the caller's end-user id is the same
+ *   value across every one of their tenants that person belongs to, so one
+ *   identity spans all of them. Per-end-user memory retrieval is gated for
+ *   these projects until per-tenant scoping lands, because that data is read
+ *   into the system prompt on every turn.
+ */
+export type TenantScope = 'dedicated' | 'gateway';
+
 export interface TenantWire {
     id: string;
     name: string;
@@ -152,6 +173,16 @@ export interface TenantWire {
     status: TenantStatus;
     /** Billing plan (migrations 023/035). Drives usage quotas. Default 'id_ego'. */
     plan: TenantPlan;
+    /**
+     * Whether this project serves one customer or fronts many of a caller's
+     * own tenants. See `TenantScope`. Default `'dedicated'` (migration 055).
+     *
+     * OPTIONAL on the wire deliberately: the backend has enforced it since
+     * 055, but it rides here additively so an older deployment in front of a
+     * newer consumer doesn't strand anyone. Read it as `'dedicated'` when
+     * absent — that is what a project that has never declared itself is.
+     */
+    tenant_scope?: TenantScope;
 
     // Time-boxed debug mode (migration 037). Populated on the LIST response
     // (joined from tenant_configs); omitted where the query does not join it.
@@ -207,6 +238,19 @@ export interface TenantUpdateBody {
     name?: string;
     description?: string;
     is_active?: boolean;
+    /**
+     * Whether this project serves one customer or fronts many of a caller's
+     * own tenants. See `TenantScope` (migration 055).
+     *
+     * ⚠️ ONE DIRECTION IS DESTRUCTIVE, and it is not the obvious one.
+     * `dedicated → gateway` is safe: it turns a privacy boundary ON.
+     * `gateway → dedicated` **re-enables per-end-user memory retrieval over
+     * rows that are still cross-tenant** — it does not undo anything, it
+     * re-opens the exposure the gateway setting was closing. A surface
+     * offering this field must confirm that direction and name what it
+     * re-enables; the reverse needs no confirmation.
+     */
+    tenant_scope?: TenantScope;
 
     industry?: TenantIndustry;
     data_residency_region?: DataResidencyRegion;

package/src/thread.d.ts

@@ -44,13 +44,22 @@ export type MessageFailureReason =
  * Conversation lifecycle state. Mirrors the CHECK constraint on
  * `egoz_threads.status` (migration 054).
  *
- * - `'draft'`  — minted by the ghosted start (`POST /egoz/conversations/draft`)
- *                before the user has typed anything. Carries the caller's
- *                init context, holds a conversation id the caller can keep,
- *                and is swept after the draft TTL if it never promotes.
- * - `'active'` — a real conversation. Every thread created by `/ask` is born
- *                active, and a draft becomes active on its first user
- *                message. An active thread is never swept.
+ * - `'draft'`   — minted by the ghosted start
+ *                 (`POST /egoz/conversations/draft`) before the user has
+ *                 typed anything. Carries the caller's init context, holds a
+ *                 conversation id the caller can keep, and lapses after the
+ *                 draft TTL if it never promotes.
+ * - `'active'`  — a real conversation. Every thread created by `/ask` is born
+ *                 active, and a draft becomes active on its first user
+ *                 message. An active thread is never swept.
+ * - `'expired'` — a lapsed draft. A TOMBSTONE, not a conversation: it cannot
+ *                 be resumed and holds no messages. It exists so that a
+ *                 caller returning with a held draft id gets a distinct
+ *                 `DraftExpired` (410) rather than a `NotFound` it cannot
+ *                 tell apart from a garbage id — the contract requires a
+ *                 lapsed draft to fail loudly and specifically, never to
+ *                 silently become a new conversation. Hard-deleted after a
+ *                 grace window.
  *
  * ORTHOGONAL TO `isActive`, which means *archived* and predates this field.
  * A draft is not an archived thread and an archived thread was never a draft;
@@ -58,7 +67,7 @@ export type MessageFailureReason =
  * draft sweeper's delete predicate would then also match archived user
  * conversations.
  */
-export type ThreadStatus = 'draft' | 'active';
+export type ThreadStatus = 'draft' | 'active' | 'expired';
 
 // ============================================================================
 // Supporting shapes