docs(metrics): clarify projection and latency contracts

docs/cordis-catalog/services.md

@@ -2323,7 +2323,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 
 /**
  * Heuristically price one model-visible message (instance face of the pure
- * {@link estimateMessage}).
+ * `estimateMessage` export from `estimate.ts`).
  * @param message - message to price without mutation.
  * @returns content and role-framing tokens under the fixed service heuristic.
  */

docs/core-data-structures/session.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/session.md
-session.md: 39fe66b43d8bb7ada0daeaca4fecc6a472b4bdf4
+session.md: 6743f26822eeb57dee6e6040224617f6e96aa69d
-session.zh.md: 67faecc6e1262a69ff078220a4a15b5103b7de20
+session.zh.md: b717b84469a93aa2359a46124a6703dd57fb24ce

docs/core-data-structures/session.md

@@ -484,8 +484,8 @@ declare class Session {
    */
   deriveMessages(): Message[];
   /**
-   * Instance face of the pure per-node projection rule
+   * Instance face of the pure per-node `deriveEventMessage` export from
-   * {@link deriveEventMessage} (see its contract in `surface.ts`).
+   * `surface.ts`.
    * @param event - the event to project.
    * @returns the derived message, or null when the event produces none.
    */

docs/core-data-structures/session.zh.md

@@ -486,8 +486,8 @@ declare class Session {
    */
   deriveMessages(): Message[];
   /**
-   * Instance face of the pure per-node projection rule
+   * Instance face of the pure per-node `deriveEventMessage` export from
-   * {@link deriveEventMessage} (see its contract in `surface.ts`).
+   * `surface.ts`.
    * @param event - the event to project.
    * @returns the derived message, or null when the event produces none.
    */

packages/client/ui-conversation/src/client/chat/turn-metrics.ts

@@ -59,8 +59,8 @@ interface TurnFold {
 /**
  * Fold assistant nodes into per-turn footer metrics.
  *
- * TTFT is the turn's lowest-step reading — the user-perceived wait before
+ * TTFT is the turn's lowest-step request-dispatch-to-first-token reading, so
- * output appeared — so it is only meaningful when the turn's start is inside
+ * it is only meaningful when the turn's start is inside
  * the loaded window (the caller gates on `turnTimings`, which shares that
  * window). Throughput divides summed output tokens by summed decode wall time,
  * counting only steps that carry both.

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -1040,7 +1040,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'estimateMessage(message: Message): number',
-        jsDoc: '/**\n * Heuristically price one model-visible message (instance face of the pure\n * {@link estimateMessage}).\n * @param message - message to price without mutation.\n * @returns content and role-framing tokens under the fixed service heuristic.\n */',
+        jsDoc: '/**\n * Heuristically price one model-visible message (instance face of the pure\n * `estimateMessage` export from `estimate.ts`).\n * @param message - message to price without mutation.\n * @returns content and role-framing tokens under the fixed service heuristic.\n */',
       },
     ],
   },

packages/core/session/src/index.ts

@@ -685,8 +685,8 @@ export class Session {
   }
 
   /**
-   * Instance face of the pure per-node projection rule
+   * Instance face of the pure per-node `deriveEventMessage` export from
-   * {@link deriveEventMessage} (see its contract in `surface.ts`).
+   * `surface.ts`.
    * @param event - the event to project.
    * @returns the derived message, or null when the event produces none.
    */

packages/llm/token-meter/src/index.ts

@@ -148,7 +148,7 @@ export class TokenMeterService extends Service {
 
   /**
    * Heuristically price one model-visible message (instance face of the pure
-   * {@link estimateMessage}).
+   * `estimateMessage` export from `estimate.ts`).
    * @param message - message to price without mutation.
    * @returns content and role-framing tokens under the fixed service heuristic.
    */