Files
HealthLog/src/__tests__/coach-stream-ios-compat.test.ts
T
Marc-André Bombeck 210becb28b feat(coach): lay down the reasoning, trail and memory contract
Add the shared contract the reasoning release builds on, with no change
to how a turn runs today.

- Schema: operator reasoning controls on app_settings (0376), the
  encrypted trail text on coach_messages (0377), and source,
  last_used_at and source_message_id on coach_facts (0378).
- Provider contract: CompletionParams.reasoning and onReasoning,
  CompletionResult.reasoning and providerState, AiMessage.providerState.
- Reasoning levels, thinking budgets and the background-job table in
  src/lib/ai/reasoning/levels.ts; coachPrefsJson.reasoning, absent
  meaning medium, salvaged field by field like every other pref.
- Stream: activity, memoryNote and planProposal frames, done.stop and
  done.withheldResults, result.interim, a compare chart kind, eight
  table refs, three more clarification kinds with an assumed choice,
  the change_assumption chip, and assumptions, activity, stop,
  memoryNote and planProposal on the provenance. Zod mirror, type
  parity and the native-client key rule cover every new frame.
- Chat request: memoryDecision and planDecision, parsed and not yet
  acted on.
- Stub contracts for the memory functions and the activity recorder,
  inert until their implementations land.
- Backup, restore and rotation carry the new columns; a fact's message
  reference is resolved against the restored messages like its
  conversation reference.
- Message keys for the trail, memory, plans, assumptions, replies,
  interim tables, comparison charts and reasoning settings in all seven
  locales, each reachable from a catalog and checked both ways.
2026-10-06 18:39:50 +02:00

111 lines
3.7 KiB
TypeScript

/**
* No Coach stream frame added after the native client shipped may carry a
* top-level key that client already decodes.
*
* The native client decodes every frame into one flat struct —
* `{ type, token, conversationId, messageId, code, message, suggestion,
* metricSource, usage }` — and dispatches on `type`, ignoring a type it does
* not know. That makes an unknown frame harmless only while its keys are
* unknown too: a new frame that reused `message` or `usage` with a different
* shape would make the whole frame fail to decode, and a new frame that
* reused one with the same shape would leak a value into whatever the client
* does with that key. So a new frame names its payload with a key of its own
* (`step`, `result`, `followUps`, `clarification`, and since v1.41
* `activity`, `memoryNote` with `note`, `planProposal` with `proposal`).
*
* Reads the frame list from the Zod mirror (`stream-events.ts`), which a
* type test holds equal to `CoachStreamEvent`, so a frame added to the
* TypeScript union is seen here too.
*
* Checked by breaking it: adding `message: z.string()` to the `step` frame in
* `stream-events.ts` turns the second test red and names the frame and key.
*/
import { describe, expect, it } from "vitest";
import { z } from "zod/v4";
import { coachStreamEventSchema } from "@/lib/ai/coach/stream-events";
/** The keys the shipped native client decodes, `type` aside. */
const NATIVE_CLIENT_KEYS = [
"token",
"conversationId",
"messageId",
"code",
"message",
"suggestion",
"metricSource",
"usage",
] as const;
/** The frames the shipped client was built against; they own those keys. */
const FRAMES_THE_CLIENT_KNOWS = new Set([
"token",
"provenance",
"suggestion",
"suggestedAction",
"reasoning",
"done",
"error",
]);
type FrameSchema = z.ZodObject<{ type: z.ZodLiteral<string> } & z.ZodRawShape>;
function frames(): Array<{ type: string; keys: string[] }> {
return (coachStreamEventSchema.options as readonly FrameSchema[]).map(
(option) => ({
type: String(option.shape.type.value),
keys: Object.keys(option.shape),
}),
);
}
/** Every `frame.key` pair where a newer frame reuses a native-client key. */
function collisions(list: Array<{ type: string; keys: string[] }>): string[] {
const reserved: ReadonlySet<string> = new Set(NATIVE_CLIENT_KEYS);
return list
.filter((frame) => !FRAMES_THE_CLIENT_KNOWS.has(frame.type))
.flatMap((frame) =>
frame.keys
.filter((key) => reserved.has(key))
.map((key) => `${frame.type}.${key}`),
);
}
describe("Coach stream frames stay decodable by the shipped native client", () => {
it("reads every frame, including the ones added after the client shipped", () => {
const types = frames().map((frame) => frame.type);
// An empty or partial list would agree with anything.
expect(types).toEqual(
expect.arrayContaining([
...FRAMES_THE_CLIENT_KNOWS,
"step",
"result",
"followUps",
"clarification",
"activity",
"memoryNote",
"planProposal",
]),
);
expect(
types.filter((type) => !FRAMES_THE_CLIENT_KNOWS.has(type)).length,
).toBeGreaterThan(0);
});
it("no newer frame carries a key the native client decodes", () => {
expect(
collisions(frames()),
"rename the payload key: the native client decodes these keys on every frame",
).toEqual([]);
});
it("the check flags a colliding frame", () => {
expect(
collisions([
{ type: "step", keys: ["type", "step", "message"] },
{ type: "done", keys: ["type", "conversationId", "messageId"] },
]),
).toEqual(["step.message"]);
});
});