77 lines
2.7 KiB
TypeScript
77 lines
2.7 KiB
TypeScript
/**
|
|
* H-AUDIT-1 contract — per-turn trace ID (turnId, UUID v4).
|
|
*
|
|
* turnId is generated ONCE at turn entry (chat.ts) and propagated EXPLICITLY
|
|
* as a parameter through every downstream stage: agent-loop → orchestrator
|
|
* recall → combined-retrieval search → prompt-assembler assemble →
|
|
* cognify (if triggered mid-turn) → tool calls → LLM request.
|
|
*
|
|
* No AsyncLocalStorage, no module-level context, no globals — propagation
|
|
* must be tsc-verifiable so a cold reader of any stage's signature can see
|
|
* whether trace is plumbed through it.
|
|
*
|
|
* Logging uses a shared pino logger tagged with `turnId`, so a single
|
|
* turnId in the log reconstructs the full turn graph (stage-by-stage with
|
|
* timestamps, input summary, output summary). This also doubles as the
|
|
* correlation key for the four-cell ablation harness JSONL output.
|
|
*
|
|
* Adoption rule: every stage entry function accepts `turnId?: string` as
|
|
* an optional parameter. Omitted = logging is silent (preserves existing
|
|
* callers that don't thread trace). When present, logs fire.
|
|
*/
|
|
|
|
import { randomUUID } from 'node:crypto';
|
|
import { createCoreLogger } from '@waggle/core';
|
|
|
|
const log = createCoreLogger('turn');
|
|
|
|
/** Generate a fresh per-turn trace ID. */
|
|
export function generateTurnId(): string {
|
|
return randomUUID();
|
|
}
|
|
|
|
export interface TurnLogPayload {
|
|
/** Stage label, e.g. 'orchestrator.recallMemory', 'retrieval.search'. */
|
|
stage: string;
|
|
[key: string]: unknown;
|
|
}
|
|
|
|
/**
|
|
* Emit a structured turn event. Silent when turnId is undefined
|
|
* (existing callers that haven't adopted trace propagation yet).
|
|
*
|
|
* Tests can opt into event capture via `startCapture()` below.
|
|
*/
|
|
export function logTurnEvent(turnId: string | undefined, payload: TurnLogPayload): void {
|
|
if (!turnId) return;
|
|
log.info(`turn.${payload.stage}`, { turnId, ...payload });
|
|
if (captureBuffer) {
|
|
captureBuffer.push({ turnId, ...payload });
|
|
}
|
|
}
|
|
|
|
// ── Test-only capture ────────────────────────────────────────────────────
|
|
|
|
export interface TurnEventRecord {
|
|
turnId: string;
|
|
stage: string;
|
|
[key: string]: unknown;
|
|
}
|
|
|
|
let captureBuffer: TurnEventRecord[] | null = null;
|
|
|
|
/**
|
|
* Start capturing turn events. Returns the buffer test code can assert on.
|
|
* Reset the buffer to capture fresh events — subsequent `startCapture`
|
|
* calls replace (not append to) the existing buffer.
|
|
*/
|
|
export function startTurnCapture(): TurnEventRecord[] {
|
|
captureBuffer = [];
|
|
return captureBuffer;
|
|
}
|
|
|
|
/** Stop capturing turn events. Events after this point go to the logger only. */
|
|
export function stopTurnCapture(): void {
|
|
captureBuffer = null;
|
|
}
|