import { isOperationId } from "./operation-id.ts"; export const DIAGNOSTIC_LEVELS = Object.freeze([ "debug", "info", "warn", "error", ] as const); export { queueSizeBucket } from "./diagnostic-buckets.ts"; export type DiagnosticLevel = (typeof DIAGNOSTIC_LEVELS)[number]; export const DIAGNOSTIC_EVENT_REGISTRY = Object.freeze({ "app.boot.failed": Object.freeze({ level: "error" }), "http.request.completed": Object.freeze({ level: "info" }), "cache.operation.failed": Object.freeze({ level: "warn" }), "storage.operation.failed": Object.freeze({ level: "warn" }), "route.changed": Object.freeze({ level: "info" }), "ui.render.failed": Object.freeze({ level: "error" }), "release.mismatch.detected": Object.freeze({ level: "warn" }), "telemetry.delivery.dropped": Object.freeze({ level: "warn" }), "feature.override.unknown": Object.freeze({ level: "warn" }), }); export type DiagnosticEventId = keyof typeof DIAGNOSTIC_EVENT_REGISTRY; export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([ "app_version", "build_id", "release_id", "active_release_id", "config_schema_version", "api_contract_version", "route_id", "operation_id", "correlation_id", "error_kind", "outcome", "http_status_group", "attempt_count_bucket", "duration_bucket", "component_boundary", "mismatch_kind", "operation", "reason", "queue_size_bucket", "feature_override_key", "effect_certainty", "scope_participant", ] as const); export type DiagnosticContextKey = (typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number]; export type DiagnosticCardinalityClass = | "bounded" | "taxonomy" | "topology" | "deployment" | "request"; /** * Cardinality ownership is explicit so a field cannot silently move from * bounded operational evidence into an unbounded metric dimension. * * `request` values are unique per request and are diagnostics-only. * `topology` values are bounded by the deployed App/Context/Feature topology. * `taxonomy` values are bounded by source-controlled error/reason taxonomies. * `deployment` values rotate with a release, not with user traffic. * `bounded` values are validated against a finite set below. */ export const DIAGNOSTIC_CONTEXT_CARDINALITY = Object.freeze({ app_version: "deployment", build_id: "deployment", release_id: "deployment", active_release_id: "deployment", config_schema_version: "deployment", api_contract_version: "deployment", route_id: "topology", operation_id: "topology", correlation_id: "request", error_kind: "taxonomy", outcome: "bounded", http_status_group: "bounded", attempt_count_bucket: "bounded", duration_bucket: "bounded", component_boundary: "bounded", mismatch_kind: "taxonomy", operation: "topology", reason: "taxonomy", queue_size_bucket: "bounded", // 09-09. A key from the deployed runtime document; it changes with a config // deployment, not with traffic. feature_override_key: "deployment", // 1103/03-05. The V3 effect certainty, five values. effect_certainty: "bounded", // 1105/02-01. The label of a scope reset participant, set in source by the // template or the product composition, never by traffic. scope_participant: "topology", } satisfies Readonly>); export type DiagnosticContext = Readonly< Partial> >; const BOUNDED_CONTEXT_VALUE_POLICIES: Readonly< Partial boolean>> > = Object.freeze({ outcome: (value) => typeof value === "string" && /^(?:success|recovered|failed|aborted|SUCCESS|PROBLEM|UNAUTHENTICATED|FORBIDDEN|RATE_LIMITED|CONTRACT_VIOLATION|TRANSPORT_FAILURE|CANCELLED|AUTH_INTEGRATION_FAILURE|FAILED|DEGRADED)$/.test( value, ), http_status_group: isHttpStatusGroup, // R-7.5. Not a finite set, but source-controlled topology: the shared // grammar applies instead of the free-form safe-string pattern. operation_id: isOperationId, attempt_count_bucket: (value) => typeof value === "string" && /^(?:1|2|3|3-4|5\+)$/.test(value), duration_bucket: (value) => typeof value === "string" && /^(?:lt100ms|100-499ms|500-1999ms|gte2000ms|unknown)$/.test(value), component_boundary: (value) => typeof value === "string" && /^(?:route|feature|boot)$/.test(value), queue_size_bucket: (value) => typeof value === "string" && /^(?:0|1-10|11-50|51\+)$/.test(value), effect_certainty: isEffectCertainty, scope_participant: isScopeParticipantLabel, }); /** * 1103/03-05. Exactly the V3 `HttpEffectCertainty` values. Telemetry and * diagnostics both validate `effect_certainty` with it. */ export function isEffectCertainty(value: unknown): value is string { return ( typeof value === "string" && /^(?:NOT_APPLICABLE|NOT_STARTED|NOT_APPLIED|APPLIED_CONFIRMED|MAYBE_APPLIED)$/.test( value, ) ); } /** * 1105/02-01. A scope reset participant's label: a lowercase kebab-case token * of at most 48 characters that starts with a letter. A failed close is * recorded under it (`scope_participant`), so the label must pass this * projection; product composition refuses any other. */ export function isScopeParticipantLabel(value: unknown): value is string { return typeof value === "string" && /^[a-z][a-z0-9-]{0,47}$/.test(value); } export type DiagnosticRecordInput = Readonly<{ level: DiagnosticLevel; eventId: DiagnosticEventId; context?: Readonly>; }>; export type DiagnosticRecord = Readonly<{ level: DiagnosticLevel; eventId: DiagnosticEventId; timestamp: string; context: DiagnosticContext; }>; const SAFE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,63}$/; function projectDiagnosticRecordUnsafe( input: DiagnosticRecordInput, now: () => number = Date.now, ): | Readonly<{ success: true; record: DiagnosticRecord }> | Readonly<{ success: false; reason: string }> { if (!Object.hasOwn(DIAGNOSTIC_EVENT_REGISTRY, input.eventId)) { return { success: false, reason: "unregistered-event" }; } if (!DIAGNOSTIC_LEVELS.includes(input.level)) { return { success: false, reason: "invalid-level" }; } const contextEntries = Object.entries(input.context ?? {}); if (contextEntries.length > DIAGNOSTIC_CONTEXT_ALLOWLIST.length) { return { success: false, reason: "invalid-context" }; } const projected: Partial< Record > = {}; for (const [key, value] of contextEntries) { if ( !DIAGNOSTIC_CONTEXT_ALLOWLIST.includes(key as DiagnosticContextKey) ) { return { success: false, reason: "unknown-context" }; } const contextKey = key as DiagnosticContextKey; const boundedPolicy = BOUNDED_CONTEXT_VALUE_POLICIES[contextKey]; if (boundedPolicy && !boundedPolicy(value)) { return { success: false, reason: "invalid-context" }; } if (boundedPolicy && typeof value === "string") { // Admitted from a finite, source-controlled set (e.g. "51+"), so the // free-form safe-string pattern does not apply. projected[contextKey] = value; } else if (typeof value === "string") { if (!SAFE_VALUE.test(value)) { return { success: false, reason: "invalid-context" }; } projected[contextKey] = value; } else if (typeof value === "number" && Number.isFinite(value)) { projected[key as DiagnosticContextKey] = value; } else if (typeof value === "boolean") { projected[key as DiagnosticContextKey] = value; } else { return { success: false, reason: "invalid-context" }; } } let timestamp: string; try { timestamp = new Date(now()).toISOString(); } catch { timestamp = new Date(0).toISOString(); } return { success: true, record: Object.freeze({ level: input.level, eventId: input.eventId, timestamp, context: Object.freeze(projected), }), }; } export function projectDiagnosticRecord( input: DiagnosticRecordInput, now: () => number = Date.now, ): ReturnType { try { return projectDiagnosticRecordUnsafe(input, now); } catch { return { success: false, reason: "serialization-failure" }; } } export function safeErrorKind(error: unknown): string { try { if (error && typeof error === "object") { const record = error as Readonly>; if ( typeof record.kind === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(record.kind) ) { return record.kind; } if ( typeof record.name === "string" && /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(record.name) ) { const normalized = record.name .replace(/([a-z0-9])([A-Z])/g, "$1_$2") .toUpperCase(); return /^[A-Z][A-Z0-9_]{0,63}$/.test(normalized) ? normalized : "UNKNOWN_FAILURE"; } } } catch { return "UNKNOWN_FAILURE"; } return "UNKNOWN_FAILURE"; } export function statusGroup(status: number | undefined): string { return typeof status === "number" && Number.isFinite(status) ? `${Math.max(0, Math.min(9, Math.floor(status / 100)))}xx` : "none"; } /** * R-7.5. Exactly the values `statusGroup` produces. Telemetry and diagnostics * both validate `http_status_group` with it. */ export function isHttpStatusGroup(value: unknown): value is string { return typeof value === "string" && /^(?:[0-9]xx|none)$/.test(value); } export function attemptBucket(attemptCount: number): string { if (attemptCount <= 1) return "1"; if (attemptCount === 2) return "2"; if (attemptCount <= 4) return "3-4"; return "5+"; } export function durationBucket(durationMs: number): string { if (!Number.isFinite(durationMs) || durationMs < 0) return "unknown"; if (durationMs < 100) return "lt100ms"; if (durationMs < 500) return "100-499ms"; if (durationMs < 2_000) return "500-1999ms"; return "gte2000ms"; }