docs: replace vague provenance prose with recorded facts

packages/session/session-title/src/index.ts

@@ -63,7 +63,7 @@ export interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 
@@ -146,14 +146,14 @@ export interface SessionTitleProviderResult {
 
 /** One optional asynchronous title implementation registered with the service. */
 export interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
@@ -615,12 +615,12 @@ export class SessionTitleService extends Service {
     let model: SessionTitleModelProvenance | undefined
     if (modelCandidate !== undefined) {
       if (modelCandidate === null || typeof modelCandidate !== 'object') {
-        throw new Error('session-title provider model provenance requires non-empty provider and model')
+        throw new Error('session-title provider result model must contain non-empty provider and model strings')
       }
       const record = modelCandidate as Record<string, unknown>
       if (typeof record.provider !== 'string' || record.provider.length === 0
         || typeof record.model !== 'string' || record.model.length === 0) {
-        throw new Error('session-title provider model provenance requires non-empty provider and model')
+        throw new Error('session-title provider result model must contain non-empty provider and model strings')
       }
       model = { provider: record.provider, model: record.model }
     }

packages/session/session-title/src/invariant.ts

@@ -16,7 +16,7 @@ export const name = 'session-title-invariant'
 export const inject = ['invariants']
 
 /**
- * Durable title-provenance invariant: an automatic title always cites at
+ * Durable title-source invariant: an automatic title always cites at
  * least one human `user/message` seq, and an explicit user rename cites none
  * — `messageSeqs` is empty iff `source.kind` is `user`. Provider revisions
  * are validated by the service before their append; this checks the durable
@@ -32,7 +32,8 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     if (event.type !== 'session/title') return
     const { source, messageSeqs } = event.data
     if ((messageSeqs.length === 0) !== (source.kind === 'user')) {
-      fail(`session/title event ${String(event.seq)} breaks provenance: source "${source.kind}" with ${String(messageSeqs.length)} cited message seq(s)`)
+      const requirement = source.kind === 'user' ? 'cite no message seqs' : 'cite at least one message seq'
+      fail(`session/title event ${String(event.seq)} with source "${source.kind}" must ${requirement}; got ${String(messageSeqs.length)}`)
     }
   }, { global: true })
 }, { inject: ['sessions'] })