refactor: replace overloaded surface terminology

packages/llm/llm-pi-ai/README.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 packages/llm/llm-pi-ai/README.md
-README.md: f6a1eefe6083d801009a5b788a07b58d6e696a5a
+README.md: abf1924a1d1297a8fb7300710223886ccf8bc931
 README.zh.md: f4c5ddd6dbe05ae709145cfac341f17a716bac82

packages/llm/llm-pi-ai/README.md

@@ -143,7 +143,7 @@ If a listener rewrites assembled assistant content, the loop drops replay state
 - pi-ai reports failures as in-stream error events; these map to `finish {kind:'error'|'aborted', failure}` chunks. Provider-specific error text distinguishes terminal `QUOTA` from transient `RATE_LIMIT`, while text and usage signals evaluated against the resolved model's context window normalize overflow to `CONTEXT_WINDOW_EXCEEDED`. A terminal `stop` whose message carries no content blocks maps to a `finish {kind:'error'}` with code `EMPTY_RESPONSE` (retried by default policy) instead of a successful empty message.
 - pi-ai folds reasoning tokens into output usage; there is no separate reasoning count to map.
 - pi-ai's `off` thinking level crosses the Harness capability seam unchanged and becomes an omitted pi-ai common `reasoning` option at dispatch.
-- `GenerateOptions.stop` is rejected with `UNSUPPORTED_OPTION` because pi-ai's common streaming surface cannot guarantee it across providers.
+- `GenerateOptions.stop` is rejected with `UNSUPPORTED_OPTION` because pi-ai's common streaming UI cannot guarantee it across providers.
 
 ## App attribution
 

packages/llm/llm/README.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 packages/llm/llm/README.md
-README.md: c74dd5705ab67d5bf4bf966cfb9004e6ae1cc3d7
+README.md: a5aa3155c57ae30d58ced3c79a3db903c675fd7e
 README.zh.md: 17a0fd92b48db3ea5122ac2f1c1ed6e116e6d6e0

packages/llm/llm/README.md

@@ -6,7 +6,7 @@ Provider-neutral LLM vocabulary and abstract service. This package defines the c
 
 ## Service: `LlmService` (ctx key: `llm`)
 
-An adapter registry plus a single streaming call surface, interceptable via a waterfall event.
+An adapter registry plus a single streaming call API, interceptable via a waterfall event.
 
 ### Public API
 
@@ -73,7 +73,7 @@ Every adapter that puts a credential in an HTTP header judges it the same way be
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and can create an identified, frozen assistant message from them. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at process boundaries.
 - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) matches its frozen serializable `failure.code`. The payload may also retain validated status, `Retry-After`, and branded provider request id facts; policy remains outside the error.
-- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
+- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic outputs (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
 - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail.
 - `QUOTA_EXCEEDED_CODE` — the non-transient provider-neutral code for exhausted account quota, balance, credits, budget, or usage limits. `isQuotaExceededError(detail)` keeps those failures distinct from request-rate limits.
 - `EMPTY_RESPONSE_CODE` — the provider-neutral code both adapters use for a degenerate provider completion: a terminal `stop` that carried no content blocks at all. Classified as an error finish (not a successful empty message) because the attempt produced nothing durable; `dsh-llm-retry` retries it by default.

packages/llm/llm/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * LLM service: adapter registry with a waterfall-interceptable streaming call
- * surface. Exports the `LlmService` default, the abstract `LlmAdapter` for
+ * API. Exports the `LlmService` default, the abstract `LlmAdapter` for
  * provider backends, and `BlockAssembler` for chunk assembly.
  *
  * @module @deepseek-ai/dsh-llm
@@ -289,7 +289,7 @@ export interface DirectoryRegistrationHandle {
 
 /**
  * The abstract `llm` service: an adapter registry plus a streaming model-call
- * surface, interceptable via the `llm/stream` waterfall.
+ * API, interceptable via the `llm/stream` waterfall.
  */
 export class LlmService extends Service {
   private adapters = new Map<string, AdapterRegistration>()

packages/llm/token-meter/tests/context-breakdown-projection.spec.ts

@@ -138,7 +138,7 @@ describe('contextBreakdown session projection', () => {
     expect(projected(ctx, session).messageTokens).toBe(estimateMessage(summary))
   })
 
-  it('keeps the message figure equal to the service surface across appends and a compaction', async () => {
+  it('keeps the message figure equal to the service result across appends and a compaction', async () => {
     const { ctx, session } = await harness()
     // The panel's composition rows and `measure()` answer the same question in
     // the same vocabulary; one shared fold is what makes that true.