@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/diagnostics/session_export.js

@@ -0,0 +1,634 @@
+import { createHash } from 'node:crypto';
+export const DIAGNOSTIC_LIMITS = Object.freeze({
+    events: 1024,
+    snapshotBytes: 1024 * 1024,
+    eventBytes: 32 * 1024,
+    textBytes: 16 * 1024,
+    markdownBytes: 128 * 1024,
+    jsonDepth: 32,
+});
+export class DiagnosticExportError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'DiagnosticExportError';
+    }
+}
+const kinds = new Set(['user', 'assistant', 'reasoning', 'tool_invocation', 'tool_result', 'system_notice',
+    'synthetic_host', 'legacy_unknown', 'runtime', 'mode', 'provider_response', 'turn_end', 'job']);
+const origins = new Set(['user', 'assistant', 'host', 'provider', 'host_tool', 'system', 'synthetic_host', 'legacy_unknown']);
+const bytes = (value) => Buffer.byteLength(value, 'utf8');
+const sha = (value) => createHash('sha256').update(value, 'utf8').digest('hex');
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const count = (value) => Number.isSafeInteger(value) && value >= 0;
+const nullableString = (value) => value === null || typeof value === 'string';
+const sensitiveKey = (key) => /^(?:api[-_]?key|(?:access|refresh|auth|session|id)[-_]?token|token|password|passwd|secret|client[-_]?secret|authorization|proxy[-_]?authorization|cookie|set[-_]?cookie|credentials?)$/i.test(key)
+    || /(?:^|[-_])(?:api[-_]?key|password|passwd|secret|(?:access|refresh|auth|session|id)[-_]?token|auth|secret[-_]?access[-_]?key)$/i.test(key);
+function jsonValid(value, depth = 0, ancestors = new Set(), budget = { remaining: 100_000 }) {
+    if (depth > DIAGNOSTIC_LIMITS.jsonDepth || --budget.remaining < 0)
+        return false;
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || ancestors.has(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+        return false;
+    ancestors.add(value);
+    try {
+        return Object.values(value).every(item => jsonValid(item, depth + 1, ancestors, budget));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function structuredString(value) {
+    if (bytes(value) > DIAGNOSTIC_LIMITS.snapshotBytes || !/^[\s]*[\[{]/.test(value))
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        return jsonValid(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function utf8Prefix(value, maximum) {
+    const buffer = Buffer.from(value, 'utf8');
+    if (buffer.length <= maximum)
+        return value;
+    let end = maximum;
+    while (end > 0 && (buffer[end] & 0xc0) === 0x80)
+        end--;
+    return buffer.subarray(0, end).toString('utf8');
+}
+function collectCredentials(value, found, depth = 0) {
+    if (typeof value === 'string') {
+        const parsed = structuredString(value);
+        if (parsed !== undefined && depth <= DIAGNOSTIC_LIMITS.jsonDepth)
+            collectCredentials(parsed, found, depth + 1);
+        return;
+    }
+    if (depth > DIAGNOSTIC_LIMITS.jsonDepth || value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectCredentials(item, found, depth + 1);
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (sensitiveKey(key) && typeof item === 'string' && item)
+            found.add(item);
+        else
+            collectCredentials(item, found, depth + 1);
+    }
+}
+function redactKnownCredentials(value, credentials) {
+    let result = value;
+    for (const credential of credentials)
+        result = result.split(credential).join('[REDACTED]');
+    return result;
+}
+function redactString(value, credentials) {
+    return redactKnownCredentials(value, credentials)
+        .replace(/-----BEGIN (?:[A-Z ]*PRIVATE KEY|OPENSSH PRIVATE KEY)-----[\s\S]*?(?:-----END (?:[A-Z ]*PRIVATE KEY|OPENSSH PRIVATE KEY)-----|$)/g, '[REDACTED PRIVATE KEY]')
+        .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9_~+/=.:-]+/gi, match => `${match.split(/\s/)[0]} [REDACTED]`)
+        .replace(/\b(?:sk-[A-Za-z0-9_-]{10,}|gh[pousr]_[A-Za-z0-9_]{10,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g, '[REDACTED]')
+        .replace(/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '[REDACTED]')
+        .replace(/\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{10,}={0,2}(?![A-Za-z0-9_-])/g, '[REDACTED]')
+        .replace(/\b(?:(?:sk|rk)_(?:live|test)_[A-Za-z0-9_]{10,}|github_pat_[A-Za-z0-9_]{10,}|npm_[A-Za-z0-9_]{10,})\b/g, '[REDACTED]')
+        .replace(/https:\/\/hooks\.(?:slack\.com|slack-gov\.com)\/services\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+/gi, '[REDACTED]')
+        .replace(/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s/@]+(?::[^\s/@]*)?@/g, '$1[REDACTED]@')
+        .replace(/([?&](?:api[-_]?key|access[-_]?token|refresh[-_]?token|token|password|secret|client[-_]?secret)=)[^\s&#]*/gi, '$1[REDACTED]')
+        .replace(/\b((?:Cookie|Set-Cookie|X-Api-Key|Api-Key)\s*:\s*)[^\r\n]*/gi, '$1[REDACTED]')
+        .replace(/("(?:api[-_]?key|access[-_]?token|refresh[-_]?token|token|password|secret|client[-_]?secret|authorization|cookie)"\s*:\s*)"(?:\\.|[^"\\])*(?:"|$)/gi, '$1"[REDACTED]"')
+        .replace(/\b((?:[A-Z_]*API_KEY|[A-Z_]*(?:ACCESS_TOKEN|AUTH_TOKEN|SECRET|PASSWORD|PASSWD)|AWS_SECRET_ACCESS_KEY|_authToken|_auth|AUTHORIZATION)\s*[=:]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;]+)/gi, '$1[REDACTED]');
+}
+function redactJson(value, credentials, depth = 0, options = {}, path = []) {
+    if (depth > DIAGNOSTIC_LIMITS.jsonDepth + 4)
+        throw new DiagnosticExportError('Invalid JSON depth in diagnostic value', 'INVALID_EXPORT');
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string') {
+        // Parse before replacement: rewriting raw JSON keys can create duplicates
+        // that JSON.parse would discard before collision handling sees them.
+        const parsed = structuredString(value);
+        if (parsed !== undefined) {
+            // Embedded JSON is authored data, independently of its enclosing schema.
+            const nested = redactJson(parsed, credentials, depth + 1);
+            if (JSON.stringify(nested) !== JSON.stringify(parsed))
+                return JSON.stringify(nested);
+        }
+        return redactString(value, credentials);
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => redactJson(item, credentials, depth + 1, options, [...path, index]));
+    if (isObject(value)) {
+        const output = {};
+        const filterNames = options.propertyNames?.(path) ?? true;
+        const entries = Object.entries(value).map(([key, item]) => ({ key, item,
+            redactedKey: filterNames ? redactKnownCredentials(key, credentials) : key }));
+        // Reserve ordinary names first, including literal placeholders and aliases,
+        // so renamed keys never take the name of a later unchanged property.
+        const used = new Set(entries.filter(entry => entry.key === entry.redactedKey).map(entry => entry.key));
+        const suffixes = new Map();
+        for (const { key, item, redactedKey } of entries) {
+            let name = redactedKey;
+            if (key !== redactedKey) {
+                let suffix = suffixes.get(redactedKey) ?? 2;
+                while (used.has(name))
+                    name = `${redactedKey} (${suffix++})`;
+                suffixes.set(redactedKey, suffix);
+                used.add(name);
+            }
+            // JSON parsing cannot change prototypes, even for literal __proto__ keys.
+            Object.defineProperty(output, name, { value: sensitiveKey(key) ? '[REDACTED]'
+                    : redactJson(item, credentials, depth + 1, options, [...path, key]), enumerable: true });
+        }
+        return output;
+    }
+    throw new DiagnosticExportError('Invalid non-JSON diagnostic value', 'INVALID_EXPORT');
+}
+/** Default credential filtering shared by persistence annotations and exports. */
+export function redactDiagnosticValue(value, options = {}) {
+    if (!jsonValid(value))
+        throw new DiagnosticExportError('Invalid, cyclic, or excessively deep JSON diagnostic value', 'INVALID_EXPORT');
+    const credentials = new Set();
+    collectCredentials(value, credentials);
+    return redactJson(value, [...credentials].sort((a, b) => b.length - a.length), 0, options);
+}
+function truncation(field, full, retained, availability) {
+    const digest = sha(full);
+    return { field, originalBytes: bytes(full), retainedBytes: Math.min(bytes(full), bytes(retained)), sha256: digest,
+        reference: `sha256:${digest}`, availability };
+}
+export function describeDiagnosticTruncation(field, fullText, retainedText, availability) {
+    const credentials = new Set();
+    collectCredentials([fullText, retainedText], credentials);
+    const known = [...credentials].sort((a, b) => b.length - a.length);
+    const full = redactJson(fullText, known);
+    const retained = redactJson(retainedText, known);
+    return truncation(field, full, retained, availability);
+}
+function boundEvent(event, credentials) {
+    if ((event.args !== undefined && !jsonValid(event.args)) || (event.data !== undefined && !jsonValid(event.data))) {
+        throw new DiagnosticExportError('Invalid JSON diagnostic event fields', 'INVALID_EXPORT');
+    }
+    const present = Object.fromEntries(Object.entries(event).filter(([, value]) => value !== undefined));
+    const redacted = redactJson(present, credentials, 0, {
+        propertyNames: path => path[0] === 'args' || path[0] === 'data',
+    });
+    const output = { ...redacted };
+    const annotations = [...(output.truncations ?? [])];
+    for (const field of ['content', 'id', 'storedRole', 'toolCallId', 'toolName', 'status']) {
+        const value = output[field];
+        if (typeof value === 'string' && bytes(value) > DIAGNOSTIC_LIMITS.textBytes) {
+            const retained = utf8Prefix(value, DIAGNOSTIC_LIMITS.textBytes);
+            output[field] = retained;
+            annotations.push(truncation(field, value, retained, 'truncated'));
+        }
+    }
+    for (const field of ['args', 'data']) {
+        const value = output[field];
+        if (value !== undefined && bytes(JSON.stringify(value)) > DIAGNOSTIC_LIMITS.textBytes) {
+            // A partial JSON argument object can imply different tool behavior. Omit
+            // the whole field and retain an explicit identity for the redacted value.
+            annotations.push(truncation(field, JSON.stringify(value), '', 'unavailable'));
+            delete output[field];
+        }
+    }
+    if (annotations.length)
+        output.truncations = annotations;
+    if (bytes(JSON.stringify(output)) > DIAGNOSTIC_LIMITS.eventBytes) {
+        for (const field of ['content', 'args', 'data']) {
+            const value = output[field];
+            if (value === undefined)
+                continue;
+            const full = typeof value === 'string' ? value : JSON.stringify(value);
+            annotations.push(truncation(field, full, '', 'unavailable'));
+            delete output[field];
+            output.truncations = annotations;
+            if (bytes(JSON.stringify(output)) <= DIAGNOSTIC_LIMITS.eventBytes)
+                break;
+        }
+    }
+    if (bytes(JSON.stringify(output)) > DIAGNOSTIC_LIMITS.eventBytes)
+        throw new DiagnosticExportError('Diagnostic event metadata exceeds its 32768-byte limit', 'LIMIT_EXCEEDED');
+    return output;
+}
+function eventValid(value) {
+    if (!isObject(value) || value.recordType !== 'event' || !nullableString(value.id) || !kinds.has(String(value.kind))
+        || !origins.has(String(value.origin)) || !nullableString(value.storedRole) || !nullableString(value.timestamp))
+        return false;
+    if (value.timestamp !== null && !Number.isFinite(Date.parse(value.timestamp)))
+        return false;
+    if (value.content !== undefined && typeof value.content !== 'string')
+        return false;
+    if (value.args !== undefined && !jsonValid(value.args))
+        return false;
+    for (const key of ['toolCallId', 'toolName', 'status'])
+        if (value[key] !== undefined && !nullableString(value[key]))
+            return false;
+    if (value.data !== undefined && (!isObject(value.data) || !jsonValid(value.data)))
+        return false;
+    if (value.truncations !== undefined) {
+        if (!Array.isArray(value.truncations) || value.truncations.length > 64)
+            return false;
+        for (const item of value.truncations) {
+            if (!isObject(item) || typeof item.field !== 'string' || !count(item.originalBytes) || !count(item.retainedBytes)
+                || item.retainedBytes > item.originalBytes || typeof item.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(item.sha256)
+                || item.reference !== `sha256:${item.sha256}` || (item.availability !== 'truncated' && item.availability !== 'unavailable'))
+                return false;
+        }
+    }
+    try {
+        return bytes(JSON.stringify(value)) <= DIAGNOSTIC_LIMITS.eventBytes;
+    }
+    catch {
+        return false;
+    }
+}
+export function createDiagnosticSnapshot() {
+    return { schemaVersion: 1, events: [], omittedEvents: 0, omittedTextBytes: 0 };
+}
+function boundedSnapshot(events, omittedEvents, omittedTextBytes, minimumOmittedEvents = 0) {
+    const sizes = events.map(event => bytes(JSON.stringify(event)));
+    let payloadBytes = sizes.reduce((total, size) => total + size, 0);
+    let dropped = 0;
+    const header = () => ({ schemaVersion: 1, events: [],
+        omittedEvents: Math.max(minimumOmittedEvents, omittedEvents + dropped), omittedTextBytes });
+    // The empty wrapper already accounts for the brackets. Every pair of
+    // adjacent retained events adds one comma; omission counters can grow too.
+    while (events.length - dropped > DIAGNOSTIC_LIMITS.events
+        || bytes(JSON.stringify(header())) + payloadBytes + Math.max(0, events.length - dropped - 1)
+            > DIAGNOSTIC_LIMITS.snapshotBytes) {
+        payloadBytes -= sizes[dropped++];
+    }
+    return { ...header(), events: events.slice(dropped) };
+}
+export function recordDiagnosticEvent(snapshot, event) {
+    if ((event.args !== undefined && !jsonValid(event.args)) || (event.data !== undefined && !jsonValid(event.data))) {
+        throw new DiagnosticExportError('Invalid, cyclic, or excessively deep JSON diagnostic event', 'INVALID_EXPORT');
+    }
+    const present = Object.fromEntries(Object.entries(event).filter(([, value]) => value !== undefined));
+    const credentials = new Set();
+    collectCredentials(event, credentials);
+    const admitted = boundEvent({ ...present, recordType: 'event' }, [...credentials].sort((a, b) => b.length - a.length));
+    if (!eventValid(admitted))
+        throw new DiagnosticExportError('Diagnostic event has invalid kind, origin, identity, or timestamp', 'INVALID_EXPORT');
+    const eventBytesOmitted = (admitted.truncations ?? []).reduce((total, item) => total + item.originalBytes - item.retainedBytes, 0);
+    const same = admitted.id === null ? -1 : snapshot.events.findIndex(item => item.id === admitted.id);
+    if (same !== -1) {
+        if (JSON.stringify(snapshot.events[same]) === JSON.stringify(admitted))
+            return structuredClone(snapshot);
+        throw new DiagnosticExportError(`Diagnostic event identity conflict: ${admitted.id}`, 'INVALID_EXPORT');
+    }
+    return boundedSnapshot([...snapshot.events, admitted], snapshot.omittedEvents, snapshot.omittedTextBytes + eventBytesOmitted);
+}
+export function mergeDiagnosticSnapshots(first, second) {
+    if (parseDiagnosticSnapshot(first) === null || parseDiagnosticSnapshot(second) === null) {
+        throw new DiagnosticExportError('Invalid diagnostic snapshot merge input', 'INVALID_EXPORT');
+    }
+    const keys = (events) => {
+        const occurrences = new Map();
+        return events.map(event => {
+            if (event.id !== null)
+                return `id:${event.id}`;
+            // Internal occurrence keys preserve repeated anonymous legacy rows. They
+            // are not exported or presented as fabricated source identities.
+            const body = JSON.stringify(event);
+            const occurrence = occurrences.get(body) ?? 0;
+            occurrences.set(body, occurrence + 1);
+            return `anonymous:${body}:${occurrence}`;
+        });
+    };
+    const firstKeys = keys(first.events);
+    const secondKeys = keys(second.events);
+    const identities = new Map(firstKeys.map((key, index) => [key, first.events[index]]));
+    const order = [...firstKeys];
+    const pending = [];
+    for (const [index, key] of secondKeys.entries()) {
+        const event = second.events[index];
+        const existing = identities.get(key);
+        if (existing !== undefined) {
+            if (JSON.stringify(existing) !== JSON.stringify(event)) {
+                identities.set(key, reconcileCheckpointFact(existing, event));
+            }
+            // A shared retained identity anchors earlier records from an old
+            // checkpoint, including when clocks are missing or equal. Appending
+            // that old prefix would instead evict new events on each repeated save.
+            if (pending.length) {
+                order.splice(order.indexOf(key), 0, ...pending);
+                pending.length = 0;
+            }
+        }
+        else {
+            identities.set(key, event);
+            pending.push(key);
+        }
+    }
+    order.push(...pending);
+    const events = order.map(key => structuredClone(identities.get(key)));
+    // Known capture times conserve chronology even when a repeated checkpoint
+    // contains older events previously dropped from the retained history. Equal
+    // or unknown times preserve their existing source order; no time is invented.
+    const chronological = events.every(item => item.timestamp !== null)
+        ? events.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)) : events;
+    // Missing event identities are not retained. Recycled drops may overlap the
+    // previous omissions, so max is an honest lower bound and repeat-save stable.
+    return boundedSnapshot(chronological, 0, Math.max(first.omittedTextBytes, second.omittedTextBytes), Math.max(first.omittedEvents, second.omittedEvents));
+}
+export function parseDiagnosticSnapshot(value) {
+    if (!isObject(value) || value.schemaVersion !== 1 || !Array.isArray(value.events) || value.events.length > DIAGNOSTIC_LIMITS.events
+        || !count(value.omittedEvents) || !count(value.omittedTextBytes) || !value.events.every(eventValid))
+        return null;
+    try {
+        if (bytes(JSON.stringify(value)) > DIAGNOSTIC_LIMITS.snapshotBytes)
+            return null;
+        const ids = value.events.flatMap(event => event.id === null ? [] : [event.id]);
+        if (new Set(ids).size !== ids.length)
+            return null;
+        return structuredClone(value);
+    }
+    catch {
+        return null;
+    }
+}
+function observedTimestamp(value) {
+    if (value instanceof Date)
+        return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+    return typeof value === 'string' && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
+}
+function priorResultTruncation(message, toolCallId) {
+    const prior = message.metadata?.toolResultTruncation;
+    if (!isObject(prior))
+        return [];
+    const value = prior[toolCallId];
+    if (!isObject(value) || !count(value.originalBytes) || !count(value.retainedBytes) || value.retainedBytes > value.originalBytes
+        || typeof value.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.sha256)
+        || value.reference !== `sha256:${value.sha256}` || (value.availability !== 'truncated' && value.availability !== 'unavailable'))
+        return [];
+    return [{ field: 'content', originalBytes: value.originalBytes, retainedBytes: value.retainedBytes, sha256: value.sha256,
+            reference: value.reference, availability: value.availability }];
+}
+function messageProvenance(message) {
+    const correction = message.metadata?.taskHandoffCorrection;
+    const deliveryState = isObject(correction) && typeof correction.deliveryState === 'string' ? correction.deliveryState : undefined;
+    const provisional = message.metadata?.steeringPending === true || message.metadata?.unsentDraft === true || deliveryState === 'pending';
+    const displayProjection = message.role === 'tool' && typeof message.metadata?.toolGroupId === 'string';
+    return { ...(provisional ? { provisional: true } : {}), ...(deliveryState === undefined ? {} : { deliveryState }),
+        ...(displayProjection ? { displayProjection: true } : {}) };
+}
+function retainedMessage(message) {
+    const provenance = messageProvenance(message);
+    return provenance.provisional !== true && provenance.displayProjection !== true;
+}
+function projectMessages(messages) {
+    const output = [];
+    for (const message of messages) {
+        const id = typeof message.id === 'string' && message.id ? message.id : null;
+        const storedRole = typeof message.role === 'string' ? message.role : null;
+        const timestamp = observedTimestamp(message.timestamp);
+        const synthetic = message.metadata?.synthetic === true;
+        const base = { recordType: 'event', id, storedRole, timestamp };
+        const provenance = messageProvenance(message);
+        if (provenance.displayProjection === true) {
+            output.push({ ...base, kind: 'synthetic_host', origin: 'host', content: message.content, data: provenance });
+            continue;
+        }
+        if (message.metadata?.toolResult === true) {
+            let blocks;
+            try {
+                blocks = JSON.parse(message.content);
+            }
+            catch {
+                blocks = null;
+            }
+            if (Array.isArray(blocks) && blocks.every(block => isObject(block) && typeof block.tool_use_id === 'string'
+                && (typeof block.content === 'string' || Array.isArray(block.content)) && (block.is_error === undefined || typeof block.is_error === 'boolean'))) {
+                for (const block of blocks) {
+                    const toolCallId = block.tool_use_id;
+                    const truncations = priorResultTruncation(message, toolCallId);
+                    output.push({ ...base, id: id === null ? null : `${id}:result:${toolCallId}`, kind: 'tool_result',
+                        origin: synthetic ? 'synthetic_host' : 'host_tool', toolCallId,
+                        content: typeof block.content === 'string' ? block.content : JSON.stringify(block.content),
+                        status: block.is_error === true ? 'error' : 'complete', ...(truncations.length ? { truncations } : {}) });
+                }
+                continue;
+            }
+            // Invalid historical structured results remain host-origin observations;
+            // they never become authored user prose or inferred completed outcomes.
+            output.push({ ...base, kind: 'tool_result', origin: synthetic ? 'synthetic_host' : 'legacy_unknown',
+                content: message.content, status: null });
+            continue;
+        }
+        const kind = synthetic ? 'synthetic_host' : message.role === 'system' ? 'system_notice'
+            : message.role === 'tool' ? 'tool_result' : message.role === 'assistant' ? message.metadata?.reasoning === true ? 'reasoning' : 'assistant'
+                : message.role === 'user' ? 'user' : 'legacy_unknown';
+        const origin = synthetic ? 'synthetic_host' : message.role === 'system' ? 'system'
+            : message.role === 'tool' ? 'legacy_unknown' : message.role === 'assistant' ? 'assistant'
+                : message.role === 'user' ? 'user' : 'legacy_unknown';
+        output.push({ ...base, kind, origin, content: message.content,
+            ...(Object.keys(provenance).length || typeof message.isStreaming === 'boolean'
+                ? { data: { ...provenance, ...(typeof message.isStreaming === 'boolean' ? { isStreaming: message.isStreaming } : {}) } } : {}) });
+        if (typeof message.metadata?.reasoningContent === 'string') {
+            output.push({ ...base, id: id === null ? null : `${id}:reasoning`, kind: 'reasoning', origin: 'assistant',
+                content: message.metadata.reasoningContent });
+        }
+        for (const call of message.toolCalls ?? []) {
+            const callId = typeof call.id === 'string' ? call.id : null;
+            output.push({ ...base, id: id === null || callId === null ? null : `${id}:invocation:${callId}`,
+                kind: 'tool_invocation', origin: synthetic ? 'synthetic_host' : 'assistant',
+                timestamp: observedTimestamp(call.startedAt) ?? timestamp, toolCallId: callId,
+                toolName: typeof call.name === 'string' ? call.name : null, args: call.args,
+                status: typeof call.status === 'string' ? call.status : null,
+                data: { completedAt: observedTimestamp(call.completedAt) } });
+        }
+    }
+    return output;
+}
+function reconcileCheckpointFact(prior, current) {
+    if (JSON.stringify(prior) === JSON.stringify(current))
+        return prior;
+    const sameSource = prior.kind === current.kind && prior.origin === current.origin && prior.storedRole === current.storedRole
+        && prior.toolCallId === current.toolCallId && prior.toolName === current.toolName;
+    if (!sameSource)
+        throw new DiagnosticExportError(`Diagnostic canonical identity conflict: ${current.id}`, 'INVALID_EXPORT');
+    if (current.kind === 'assistant' || current.kind === 'reasoning') {
+        const authoredFacts = (event) => {
+            const fact = { ...event, timestamp: null };
+            if (fact.data !== undefined) {
+                fact.data = { ...fact.data };
+                if (typeof fact.data.isStreaming === 'boolean')
+                    delete fact.data.isStreaming;
+                if (Object.keys(fact.data).length === 0)
+                    delete fact.data;
+            }
+            return JSON.stringify(fact);
+        };
+        if (authoredFacts(prior) === authoredFacts(current)) {
+            const observedStreaming = prior.data?.isStreaming === false || current.data?.isStreaming === false
+                ? false : prior.data?.isStreaming ?? current.data?.isStreaming;
+            const data = { ...prior.data, ...current.data,
+                ...(observedStreaming === undefined ? {} : { isStreaming: observedStreaming }) };
+            const reconciled = { ...prior, timestamp: prior.timestamp ?? current.timestamp };
+            if (Object.keys(data).length)
+                reconciled.data = data;
+            else
+                delete reconciled.data;
+            return reconciled;
+        }
+    }
+    if (current.kind === 'tool_invocation') {
+        const terminal = (status) => status === 'complete' || status === 'error';
+        if (terminal(prior.status)) {
+            if (!terminal(current.status))
+                return prior; // A stale live checkpoint cannot reopen a settled call.
+            if (prior.status !== current.status || JSON.stringify(prior.args) !== JSON.stringify(current.args)) {
+                throw new DiagnosticExportError(`Diagnostic settled invocation identity conflict: ${current.id}`, 'INVALID_EXPORT');
+            }
+            if (JSON.stringify(prior.data) === JSON.stringify(current.data))
+                return prior;
+            if (prior.data?.completedAt === current.data?.completedAt)
+                return { ...current, data: { ...prior.data, ...current.data } };
+            if (prior.data?.completedAt === null && typeof current.data?.completedAt === 'string')
+                return current;
+            if (current.data?.completedAt === null)
+                return prior;
+        }
+        else if (prior.status === 'running' && current.status === 'pending')
+            return prior;
+        else if (['pending', 'running', 'complete', 'error'].includes(current.status ?? '')) {
+            return { ...current, data: { ...current.data,
+                    ...(JSON.stringify(prior.args) === JSON.stringify(current.args) ? {} : {
+                        argumentsUpdatedFromPriorCheckpoint: true,
+                        argumentsSource: 'latest canonical checkpoint; model proposal can differ from admitted execution input',
+                    }) } };
+        }
+    }
+    if (current.kind === 'tool_result' && prior.status === current.status) {
+        const sourceIdentity = (event) => event.truncations?.find(row => row.field === 'content')?.sha256
+            ?? (event.content === undefined ? null : sha(event.content));
+        const priorIdentity = sourceIdentity(prior);
+        const currentIdentity = sourceIdentity(current);
+        if (priorIdentity !== null && priorIdentity === currentIdentity) {
+            return bytes(prior.content ?? '') >= bytes(current.content ?? '') ? prior : current;
+        }
+    }
+    if ((current.kind === 'assistant' || current.kind === 'reasoning') && prior.data?.isStreaming === true)
+        return current;
+    throw new DiagnosticExportError(`Diagnostic canonical identity conflict: ${current.id}`, 'INVALID_EXPORT');
+}
+/** Capture canonical message facts before checkpoint trimming or compaction.
+ * Telemetry remains immutable; only a matching canonical invocation may advance
+ * its observed lifecycle, and a matching result may retain a richer same-source preview. */
+export function captureSessionDiagnosticSnapshot(input) {
+    const history = input.diagnostics === undefined ? createDiagnosticSnapshot() : parseDiagnosticSnapshot(input.diagnostics);
+    if (history === null)
+        throw new DiagnosticExportError('Invalid diagnostic snapshot', 'INVALID_EXPORT');
+    const projected = projectMessages(input.messages.filter(retainedMessage));
+    // Credential context includes provisional rows even though their mutable
+    // facts are excluded from retention; another admitted row can echo a secret.
+    const credentials = new Set();
+    collectCredentials([input.messages, history.events], credentials);
+    const known = [...credentials].sort((a, b) => b.length - a.length);
+    const prior = history.events.map(event => boundEvent(event, known));
+    const current = projected.map(event => boundEvent(event, known));
+    const positions = new Map(prior.flatMap((event, index) => event.id === null ? [] : [[event.id, index]]));
+    for (const [index, event] of current.entries()) {
+        const position = event.id === null ? undefined : positions.get(event.id);
+        if (position === undefined)
+            continue;
+        const reconciled = reconcileCheckpointFact(prior[position], event);
+        prior[position] = reconciled;
+        current[index] = reconciled;
+    }
+    const omittedBytes = (events) => events.reduce((total, event) => total
+        + (event.truncations ?? []).reduce((sum, row) => sum + row.originalBytes - row.retainedBytes, 0), 0);
+    const previous = boundedSnapshot(prior, history.omittedEvents, Math.max(history.omittedTextBytes, omittedBytes(prior)));
+    const fresh = boundedSnapshot(current, 0, omittedBytes(current));
+    return mergeDiagnosticSnapshots(previous, fresh);
+}
+export function buildSessionDiagnosticDocument(input) {
+    if (input.sessionId !== undefined && input.sessionId !== null
+        && (typeof input.sessionId !== 'string' || bytes(input.sessionId) > DIAGNOSTIC_LIMITS.textBytes)) {
+        throw new DiagnosticExportError('Diagnostic session header identity exceeds its 16384-byte limit', 'LIMIT_EXCEEDED');
+    }
+    let snapshot = captureSessionDiagnosticSnapshot(input);
+    const credentials = new Set();
+    collectCredentials([input.messages, input.diagnostics?.events ?? []], credentials);
+    const known = [...credentials].sort((a, b) => b.length - a.length);
+    // Pending inputs and mutable display cards remain useful live observations,
+    // but never enter the durable ledger as immutable admitted source facts.
+    const live = projectMessages(input.messages.filter(message => !retainedMessage(message)))
+        .map(event => boundEvent(event, known));
+    const liveOmittedBytes = live.reduce((total, event) => total
+        + (event.truncations ?? []).reduce((sum, row) => sum + row.originalBytes - row.retainedBytes, 0), 0);
+    snapshot = mergeDiagnosticSnapshots(snapshot, boundedSnapshot(live, 0, liveOmittedBytes));
+    return { header: { recordType: 'header', schemaVersion: 1, sessionId: input.sessionId === undefined || input.sessionId === null ? null : redactString(input.sessionId, known), redacted: true,
+            omittedEvents: snapshot.omittedEvents, omittedTextBytes: snapshot.omittedTextBytes }, events: snapshot.events };
+}
+export function exportSessionDiagnostics(input) {
+    const document = buildSessionDiagnosticDocument(input);
+    return [document.header, ...document.events].map(record => JSON.stringify(record)).join('\n') + '\n';
+}
+export function parseDiagnosticExport(text) {
+    if (bytes(text) > DIAGNOSTIC_LIMITS.snapshotBytes + DIAGNOSTIC_LIMITS.eventBytes)
+        throw new DiagnosticExportError('Diagnostic export exceeds its byte limit', 'LIMIT_EXCEEDED');
+    let records;
+    try {
+        records = text.trim().split('\n').map(line => JSON.parse(line));
+    }
+    catch {
+        throw new DiagnosticExportError('Diagnostic export must contain valid JSONL records', 'INVALID_EXPORT');
+    }
+    const header = records[0];
+    if (!isObject(header) || header.recordType !== 'header')
+        throw new DiagnosticExportError('Diagnostic export requires a header record', 'INVALID_EXPORT');
+    if (header.schemaVersion !== 1)
+        throw new DiagnosticExportError('Diagnostic export requires schemaVersion=1', 'UNSUPPORTED_SCHEMA');
+    if (!nullableString(header.sessionId) || (header.sessionId !== null && bytes(header.sessionId) > DIAGNOSTIC_LIMITS.textBytes)
+        || bytes(JSON.stringify(header)) > DIAGNOSTIC_LIMITS.eventBytes || header.redacted !== true || !count(header.omittedEvents) || !count(header.omittedTextBytes)
+        || records.length - 1 > DIAGNOSTIC_LIMITS.events || !records.slice(1).every(eventValid))
+        throw new DiagnosticExportError('Diagnostic export contains invalid header or events', 'INVALID_EXPORT');
+    const events = records.slice(1);
+    const ids = events.flatMap(item => item.id === null ? [] : [item.id]);
+    if (new Set(ids).size !== ids.length)
+        throw new DiagnosticExportError('Diagnostic export contains duplicate event identity', 'INVALID_EXPORT');
+    const credentials = new Set();
+    collectCredentials(events, credentials);
+    const known = [...credentials].sort((a, b) => b.length - a.length);
+    return { header: { ...header, sessionId: header.sessionId === null ? null : redactString(header.sessionId, known) },
+        events: events.map(item => boundEvent(item, known)) };
+}
+const headings = {
+    user: 'User', assistant: 'Assistant', reasoning: 'Reasoning', tool_invocation: 'Tool invocation', tool_result: 'Tool result',
+    system_notice: 'System notice', synthetic_host: 'Synthetic host', legacy_unknown: 'Legacy unknown', runtime: 'Runtime capabilities', mode: 'Mode change',
+    provider_response: 'Provider response', turn_end: 'Turn end', job: 'Command job',
+};
+export function formatSessionDiagnosticsMarkdown(input) {
+    const document = buildSessionDiagnosticDocument(input);
+    const parts = [`# ZTC session diagnostics (v1)\n\nSession: ${document.header.sessionId ?? 'unknown'}\nCredential redaction: enabled.\n`];
+    let omitted = 0;
+    for (const event of document.events) {
+        const details = [event.content ?? '', event.args === undefined ? '' : `Arguments: ${JSON.stringify(event.args)}`,
+            event.data === undefined ? '' : `Details: ${JSON.stringify(event.data)}`].filter(Boolean).join('\n\n');
+        const references = (event.truncations ?? []).map(item => `Omitted ${item.field}: ${item.originalBytes - item.retainedBytes} bytes; ${item.reference}; availability=${item.availability}. A digest alone cannot retrieve omitted content.`).join('\n');
+        const row = `\n## ${headings[event.kind]}\n\nID: ${event.id ?? 'unknown'}; timestamp: ${event.timestamp ?? 'unknown'}; origin: ${event.origin}; stored role: ${event.storedRole ?? 'unknown'}${event.toolCallId === undefined ? '' : `; tool ID: ${event.toolCallId ?? 'unknown'}`}${event.toolName === undefined ? '' : `; tool: ${event.toolName ?? 'unknown'}`}${event.status === undefined ? '' : `; status: ${event.status ?? 'unknown'}`}\n\n${details}\n${references}\n`;
+        if (bytes(parts.join('')) + bytes(row) > DIAGNOSTIC_LIMITS.markdownBytes - 1024) {
+            omitted++;
+            continue;
+        }
+        parts.push(row);
+    }
+    parts.push(`\nExport omissions: at least ${document.header.omittedEvents} retained-history events and ${document.header.omittedTextBytes} text bytes; ${omitted} additional events omitted from Markdown. JSONL contains the retained event records. Truncated/unavailable content requires its original retained source, not its digest alone.\n`);
+    return parts.join('');
+}