From a17eebcaca7c7f2351775919c801db939e669d1f Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 6 Aug 2026 00:22:09 +0800 Subject: [PATCH] docs(metrics): clarify projection and latency contracts --- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/session.i18n.yaml | 4 ++-- docs/core-data-structures/session.md | 4 ++-- docs/core-data-structures/session.zh.md | 4 ++-- .../client/ui-conversation/src/client/chat/turn-metrics.ts | 4 ++-- packages/cordis/tool-cordis/src/api-catalog.ts | 2 +- packages/core/session/src/index.ts | 4 ++-- packages/llm/token-meter/src/index.ts | 2 +- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 5099100113..2c34e4fc78 100644 --- a/docs/cordis-catalog/services.md +++ b/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. */ diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml index 221fac1e42..942f997866 100644 --- a/docs/core-data-structures/session.i18n.yaml +++ b/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.zh.md: 67faecc6e1262a69ff078220a4a15b5103b7de20 +session.md: 6743f26822eeb57dee6e6040224617f6e96aa69d +session.zh.md: b717b84469a93aa2359a46124a6703dd57fb24ce diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index 39fe66b43d..6743f26822 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -484,8 +484,8 @@ declare class Session { */ deriveMessages(): Message[]; /** - * Instance face of the pure per-node projection rule - * {@link deriveEventMessage} (see its contract in `surface.ts`). + * Instance face of the pure per-node `deriveEventMessage` export from + * `surface.ts`. * @param event - the event to project. * @returns the derived message, or null when the event produces none. */ diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md index 67faecc6e1..b717b84469 100644 --- a/docs/core-data-structures/session.zh.md +++ b/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 - * {@link deriveEventMessage} (see its contract in `surface.ts`). + * Instance face of the pure per-node `deriveEventMessage` export from + * `surface.ts`. * @param event - the event to project. * @returns the derived message, or null when the event produces none. */ diff --git a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts index 156a4c0e9d..b7cc5ddb72 100644 --- a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts +++ b/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 - * output appeared — so it is only meaningful when the turn's start is inside + * TTFT is the turn's lowest-step request-dispatch-to-first-token reading, so + * 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. diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 47dc53ec53..d7f36e7d81 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/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 */', }, ], }, diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index b790eb115c..2c9c8de072 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -685,8 +685,8 @@ export class Session { } /** - * Instance face of the pure per-node projection rule - * {@link deriveEventMessage} (see its contract in `surface.ts`). + * Instance face of the pure per-node `deriveEventMessage` export from + * `surface.ts`. * @param event - the event to project. * @returns the derived message, or null when the event produces none. */ diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts index 594cc51e5f..31991b482a 100644 --- a/packages/llm/token-meter/src/index.ts +++ b/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. */