--- id: STATE-PFM-LLM-008 title: Jazz AI conversation lifecycle object: DOM-PFM-LLM-005 product_area: platform module: llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f states: - name: absent meaning: 'The process store has no conversation, because it was never created, was deleted or was lost on restart.' - name: new meaning: A conversation exists without messages; its title may already have been renamed. - name: active meaning: An unarchived conversation contains messages and appears in active views. - name: archived meaning: The archive marker hides the conversation from active lists while retaining its content. transitions: - from: absent to: new trigger: A person starts a general chat. guard: Creation accepts optional project filing and falls back to unfiled when that project is unavailable. side_effects: - Create an empty conversation with its supplied or default title. who: 'Workspace Staff Member, through the console''s conversation routes' provenance: observed source: 'react-console:lib/agent/store.ts:createConversation' - from: absent to: active trigger: A query or directory opens its scoped history. guard: No matching scope identity has been found. side_effects: - Create a scoped conversation with a refinement title and any existing messages. who: The query workspace or record directory on the person's behalf provenance: observed source: 'react-console:components/queries/query-workspace.tsx:openRefine' - from: new to: active trigger: The first exchange is appended. guard: The conversation exists for the sample owner. side_effects: - Replace only a default title with the normalized first-person-message title. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:appendMessages' - from: active to: active trigger: Messages or conversation metadata change. guard: The conversation exists and any new project is valid. side_effects: - Advance update time and retain the resulting messages or metadata. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:updateConversation' - from: active to: archived trigger: A person archives an active conversation. guard: The conversation exists for the sample owner. side_effects: - Set archive and update times; archiving the open chat starts a fresh chat view. who: Workspace Staff Member provenance: observed source: 'react-console:components/agent/conversation-browser.tsx:onArchive' - from: archived to: active trigger: A person restores history or scoped creation finds it archived. guard: The conversation exists for the sample owner. side_effects: - Clear archive time; direct scoped reuse need not advance update time. who: 'Workspace Staff Member, or the scoped work on their behalf' provenance: observed source: 'react-console:lib/agent/store.ts:createConversation' - from: active to: absent trigger: A person confirms active-conversation deletion. guard: The conversation exists for the sample owner. side_effects: - Remove the conversation and its messages from memory. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:deleteConversation' - from: archived to: absent trigger: Archived history is deleted or the server process restarts. guard: Deletion requires an existing conversation; restart affects every stored state. side_effects: - 'Remove the selected history, or recreate the sample store after restart.' who: 'Workspace Staff Member, or the hosting platform' provenance: observed source: 'react-console:lib/agent/store.ts:db' - from: new to: archived trigger: A person archives an empty conversation. guard: The conversation exists for the sample owner. side_effects: - Set archive and update timestamps without requiring messages. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:updateConversation' - from: new to: absent trigger: A person deletes an empty conversation. guard: The conversation exists for the sample owner. side_effects: - Remove its memory entry. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:deleteConversation' - from: new to: new trigger: A person renames or refiles an empty conversation. guard: The conversation exists and any target project is valid. side_effects: - Change metadata and update time while leaving messages empty. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:updateConversation' - from: archived to: archived trigger: A caller appends messages to archived history. guard: The conversation exists for the sample owner. side_effects: - Append messages and advance update time without clearing archive. who: Workspace Staff Member provenance: observed source: 'react-console:lib/agent/store.ts:appendMessages' invalid: - from: archived to: new why: Restoring archive preserves messages; there is no command that empties them. - from: active to: new why: 'Metadata can rename any conversation, but no supported operation resets an existing history to empty.' - from: absent to: archived why: New creation clears archive; archiving is a subsequent metadata operation. concurrency: >- Memory mutations have no durable transaction or version guard. Simultaneous model replies read earlier history and append in completion order. Deletion during generation can return success without a conversation. Instances do not share stores and restart restores sample data. invariants: - INV-DOM-PFM-LLM-005-01 - INV-DOM-PFM-LLM-005-02 - INV-DOM-PFM-LLM-005-05 - INV-DOM-PFM-LLM-005-06 evidence: - >- react-console at baf6dae: lib/agent/store.ts, types.ts, schemas.ts; app/api/agent/**; components/agent/conversation-browser.tsx; components/console/agent-chat.tsx; components/queries/query-workspace.tsx. --- # Jazz AI conversation lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 absent --> new absent --> active new --> active active --> active active --> archived archived --> active active --> absent archived --> absent new --> archived new --> absent new --> new archived --> archived ``` ## Transitions Explained General chat can begin empty, while scoped creation can import earlier exchanges. Empty conversations can be renamed, archived or deleted. Archive is a visibility flag: store operations can still append messages or change metadata. Restoring an empty archived conversation leaves it empty. Project deletion removes filing without deleting its conversations. ## What Cannot Happen The store has no clear-history command. General model replies reject scoped conversations, but the append path records externally produced turns. Scope edits can create duplicate scope identities despite normal creation reuse. ## Concurrency and Timing A model answer is appended after generation, so the underlying conversation can change or disappear while waiting. Restart loses every authored conversation regardless of state; the sample records are then seeded again.