Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { match } from 'ts-pattern';
import type { CacheRequest } from './protocol';
/** Fixed cache telemetry names. Dashboards must not accept ad-hoc names. */
export const CACHE_TELEMETRY_EVENT_NAMES = [
'graphql_cache.wasm_download',
'graphql_cache.wasm_compile',
'graphql_cache.wasm_instantiate',
'graphql_cache.schema_init',
'graphql_cache.db_ready',
'graphql_cache.host_ready',
'graphql_cache.registration_retry',
'graphql_cache.host_request',
'graphql_cache.coordinator_request',
'graphql_cache.engine_request',
'graphql_cache.transaction',
'graphql_cache.read',
'graphql_cache.slow_query',
'graphql_cache.owner',
'graphql_cache.stale_drop',
'graphql_cache.lock_wait',
'graphql_cache.storage_reset_required',
'graphql_cache.logical_reset',
'graphql_cache.revision_advance',
'graphql_cache.change_batch',
'graphql_cache.reset_wipe',
'graphql_cache.origin_storage_pressure',
'graphql_cache.linear_memory',
'graphql_cache.queue_diagnostics',
'graphql_cache.navigation',
'graphql_cache.aggregate',
] as const;
export type CacheTelemetryEventName =
(typeof CACHE_TELEMETRY_EVENT_NAMES)[number];
export const CACHE_OPERATION_CATEGORIES = [
'initialization',
'read',
'write',
'transaction',
'queue',
'inspection',
'invalidation',
'lifecycle',
'storage',
'navigation',
'unknown',
] as const;
export type CacheOperationCategory =
(typeof CACHE_OPERATION_CATEGORIES)[number];
export const CACHE_TELEMETRY_OUTCOMES = [
'success',
'error',
'hit',
'miss',
'graceful',
'abrupt',
'granted',
'denied',
'unknown',
] as const;
export type CacheTelemetryOutcome = (typeof CACHE_TELEMETRY_OUTCOMES)[number];
export const CACHE_OPEN_OUTCOMES = [
'opened-existing',
'opened-new',
'reset-incompatible',
'reset-corrupt',
'reset-storage-uncertain',
] as const;
export type CacheOpenOutcome = (typeof CACHE_OPEN_OUTCOMES)[number];
export const CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY = [
'available',
'unavailable',
] as const;
export type CacheQueueDiagnosticsAvailability =
(typeof CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY)[number];
export const CACHE_REVISION_CATEGORIES = [
'authoritative-write',
'optimistic-enqueue',
'optimistic-commit',
'optimistic-rollback',
'external-invalidation',
'deletion',
'clear',
] as const;
export type CacheRevisionCategory = (typeof CACHE_REVISION_CATEGORIES)[number];
/** Payload-free, bounded error classes shared by all cache layers. */
export const CACHE_ERROR_CODES = [
'none',
'unsupported',
'timeout',
'wasm-download',
'wasm-compile',
'wasm-instantiate',
'schema',
'integrity',
'opfs-unavailable',
'opfs-quota',
'opfs-io',
'lock',
'owner-lost',
'protocol',
'transport',
'storage-reset',
'initialization',
'unknown',
] as const;
export type CacheErrorCode = (typeof CACHE_ERROR_CODES)[number];
export const CACHE_RESET_REASONS = [
'explicit-clear',
'identity-change',
'namespace-mismatch',
'integrity-failure',
'storage-reset-required',
'abrupt-owner-loss',
'storage-eviction',
'quota-failure',
'unknown',
] as const;
export type CacheResetReason = (typeof CACHE_RESET_REASONS)[number];
export const CACHE_OWNER_EVENTS = [
'elected',
'activated',
'graceful-drain-started',
'graceful-drain-completed',
'visibility-handoff-started',
'visibility-handoff-blocked',
'visibility-handoff-completed',
'park-started',
'parked',
'unpark-started',
'unpark-completed',
'navigation-departure',
'coordinator-restarted',
'abrupt-loss',
'replacement',
'multiple-owner-detected',
'owner-lock-unavailable',
'storage-busy',
'takeover-granted',
'superseded',
'stale-databases-removed',
'stale-database-kept',
] as const;
export type CacheOwnerEvent = (typeof CACHE_OWNER_EVENTS)[number];
export const CACHE_ROLLOUT_COHORTS = [
'control',
'treatment',
'override',
'unknown',
] as const;
export type CacheRolloutCohort = (typeof CACHE_ROLLOUT_COHORTS)[number];
export type CacheTelemetryObservation = {
name: CacheTelemetryEventName;
/** Original fixed event name represented by an aggregate envelope. */
aggregatedEventName?: CacheTelemetryEventName;
operationCategory: CacheOperationCategory;
outcome?: CacheTelemetryOutcome;
errorCode?: CacheErrorCode;
resetReason?: CacheResetReason;
ownerEvent?: CacheOwnerEvent;
persistence?: 'granted' | 'denied' | 'unknown';
openOutcome?: CacheOpenOutcome;
queueDiagnosticsAvailability?: CacheQueueDiagnosticsAvailability;
revisionCategory?: CacheRevisionCategory;
resetAttempt?: 'wipe-before-open';
durationMs?: number;
/** FNV-1a of the unexpanded SQL template; never SQL text or bound values. */
queryFingerprint?: string;
bytes?: number;
highWaterBytes?: number;
usageBytes?: number;
quotaBytes?: number;
ratio?: number;
count?: number;
sampleRate?: number;
queueDepth?: number;
oldestAgeMs?: number;
};
/** The only cohort/browser/backend dimensions permitted on exported events. */
export type CacheTelemetryContext = {
browserFamily: 'chromium' | 'firefox' | 'safari' | 'other';
browserVersion: string;
appVersion: string;
backend: 'turso-wasm-opfs';
rolloutCohort: CacheRolloutCohort;
};
export type CacheTelemetryEnvelope = Readonly<
CacheTelemetryContext & CacheTelemetryObservation
>;
export interface CacheTelemetryObservationSink {
emit(observation: CacheTelemetryObservation): void;
}
export interface CacheTelemetrySink {
emit(event: CacheTelemetryEnvelope): void;
}
export interface CacheTelemetryRecorderLike {
record(observation: CacheTelemetryObservation): void;
flush(): void;
}
const HIGH_VOLUME_NAMES = new Set<CacheTelemetryEventName>([
'graphql_cache.host_request',
'graphql_cache.coordinator_request',
'graphql_cache.engine_request',
'graphql_cache.transaction',
'graphql_cache.read',
]);
const boundedNumber = (
value: number | undefined,
maximum = Number.MAX_SAFE_INTEGER
): number | undefined =>
value !== undefined && Number.isFinite(value) && value >= 0
? Math.min(value, maximum)
: undefined;
function sanitizeObservation(
input: CacheTelemetryObservation
): CacheTelemetryObservation | undefined {
if (!CACHE_TELEMETRY_EVENT_NAMES.includes(input.name)) return;
if (!CACHE_OPERATION_CATEGORIES.includes(input.operationCategory)) return;
return {
name: input.name,
...(input.name === 'graphql_cache.aggregate' &&
input.aggregatedEventName !== undefined &&
HIGH_VOLUME_NAMES.has(input.aggregatedEventName)
? { aggregatedEventName: input.aggregatedEventName }
: {}),
operationCategory: input.operationCategory,
...(input.outcome !== undefined &&
CACHE_TELEMETRY_OUTCOMES.includes(input.outcome)
? { outcome: input.outcome }
: {}),
...(input.errorCode !== undefined &&
CACHE_ERROR_CODES.includes(input.errorCode)
? { errorCode: input.errorCode }
: {}),
...(input.resetReason !== undefined &&
CACHE_RESET_REASONS.includes(input.resetReason)
? { resetReason: input.resetReason }
: {}),
...(input.ownerEvent !== undefined &&
CACHE_OWNER_EVENTS.includes(input.ownerEvent)
? { ownerEvent: input.ownerEvent }
: {}),
...(input.persistence === 'granted' ||
input.persistence === 'denied' ||
input.persistence === 'unknown'
? { persistence: input.persistence }
: {}),
...(input.openOutcome !== undefined &&
CACHE_OPEN_OUTCOMES.includes(input.openOutcome)
? { openOutcome: input.openOutcome }
: {}),
...(input.queueDiagnosticsAvailability !== undefined &&
CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY.includes(
input.queueDiagnosticsAvailability
)
? {
queueDiagnosticsAvailability: input.queueDiagnosticsAvailability,
}
: {}),
...(input.revisionCategory !== undefined &&
CACHE_REVISION_CATEGORIES.includes(input.revisionCategory)
? { revisionCategory: input.revisionCategory }
: {}),
...(input.resetAttempt === 'wipe-before-open'
? { resetAttempt: input.resetAttempt }
: {}),
...(boundedNumber(input.durationMs, 3_600_000) !== undefined
? { durationMs: boundedNumber(input.durationMs, 3_600_000) }
: {}),
...(input.name === 'graphql_cache.slow_query' &&
typeof input.queryFingerprint === 'string' &&
/^[0-9a-f]{16}$/.test(input.queryFingerprint)
? { queryFingerprint: input.queryFingerprint }
: {}),
...(boundedNumber(input.bytes) !== undefined
? { bytes: boundedNumber(input.bytes) }
: {}),
...(boundedNumber(input.highWaterBytes) !== undefined
? { highWaterBytes: boundedNumber(input.highWaterBytes) }
: {}),
...(boundedNumber(input.usageBytes) !== undefined
? { usageBytes: boundedNumber(input.usageBytes) }
: {}),
...(boundedNumber(input.quotaBytes) !== undefined
? { quotaBytes: boundedNumber(input.quotaBytes) }
: {}),
...(boundedNumber(input.ratio, 1) !== undefined
? { ratio: boundedNumber(input.ratio, 1) }
: {}),
...(boundedNumber(input.count) !== undefined
? { count: boundedNumber(input.count) }
: {}),
...(boundedNumber(input.sampleRate) !== undefined
? { sampleRate: boundedNumber(input.sampleRate) }
: {}),
...(boundedNumber(input.queueDepth) !== undefined
? { queueDepth: boundedNumber(input.queueDepth) }
: {}),
...(boundedNumber(input.oldestAgeMs, 31_536_000_000) !== undefined
? { oldestAgeMs: boundedNumber(input.oldestAgeMs, 31_536_000_000) }
: {}),
};
}
type Aggregate = {
template: CacheTelemetryObservation;
count: number;
totalDurationMs: number;
};
/**
* Exception-isolated recorder. High-volume successes are counted in bounded
* aggregates and sampled; every error remains individually visible.
*/
export class CacheTelemetryRecorder implements CacheTelemetryRecorderLike {
private readonly sampleSequences = new Map<string, number>();
private readonly aggregates = new Map<string, Aggregate>();
constructor(
private readonly sink: CacheTelemetryObservationSink,
private readonly sampleRate = 100,
private readonly aggregateEvery = 50
) {}
record(input: CacheTelemetryObservation): void {
try {
const observation = sanitizeObservation(input);
if (!observation) return;
if (!HIGH_VOLUME_NAMES.has(observation.name)) {
this.safeEmit(observation);
return;
}
const isError =
observation.outcome === 'error' ||
observation.errorCode === 'owner-lost';
if (isError) {
// Make the denominator current before the raw error is observable.
// Matching successes remain counted exactly once in aggregates.
this.flushMatchingSuccesses(observation);
this.safeEmit({ ...observation, sampleRate: 1 });
return;
}
const key = JSON.stringify([
observation.name,
observation.operationCategory,
observation.outcome ?? 'unknown',
observation.errorCode ?? 'none',
]);
const aggregate = this.aggregates.get(key) ?? {
template: observation,
count: 0,
totalDurationMs: 0,
};
const weight = observation.count ?? 1;
aggregate.count += weight;
aggregate.totalDurationMs += (observation.durationMs ?? 0) * weight;
this.aggregates.set(key, aggregate);
if (aggregate.count >= this.aggregateEvery) this.flushOne(key, aggregate);
const sampleSequence = (this.sampleSequences.get(key) ?? 0) + 1;
this.sampleSequences.set(key, sampleSequence);
const mustEmit =
this.sampleRate <= 1 || sampleSequence % this.sampleRate === 0;
if (mustEmit) {
this.safeEmit({
...observation,
sampleRate: this.sampleRate,
});
}
} catch {
// Telemetry is deliberately unable to affect cache correctness.
}
}
flush(): void {
try {
for (const [key, aggregate] of this.aggregates) {
this.flushOne(key, aggregate);
}
} catch {
// A broken sink must not escape lifecycle cleanup.
}
}
private flushMatchingSuccesses(error: CacheTelemetryObservation): void {
for (const [key, aggregate] of this.aggregates) {
if (aggregate.template.name === error.name) {
this.flushOne(key, aggregate);
}
}
}
private flushOne(key: string, aggregate: Aggregate): void {
this.aggregates.delete(key);
const durationMs =
aggregate.count > 0
? aggregate.totalDurationMs / aggregate.count
: undefined;
this.safeEmit({
name: 'graphql_cache.aggregate',
aggregatedEventName: aggregate.template.name,
operationCategory: aggregate.template.operationCategory,
outcome: aggregate.template.outcome,
errorCode: aggregate.template.errorCode,
count: aggregate.count,
durationMs,
sampleRate: 1,
});
}
private safeEmit(observation: CacheTelemetryObservation): void {
try {
this.sink.emit(observation);
} catch {
// Failure isolation is part of the telemetry contract.
}
}
}
/** Adds allowlisted runtime dimensions and strips every unknown property. */
export class CacheTelemetryReporter implements CacheTelemetryObservationSink {
private readonly context: CacheTelemetryContext;
constructor(
context: CacheTelemetryContext,
private readonly sink: CacheTelemetrySink
) {
this.context = {
browserFamily: ['chromium', 'firefox', 'safari', 'other'].includes(
context.browserFamily
)
? context.browserFamily
: 'other',
browserVersion: /^\d{1,3}$/.test(context.browserVersion)
? context.browserVersion
: 'unknown',
appVersion: /^\d+\.\d+$/.test(context.appVersion)
? context.appVersion.slice(0, 16)
: 'unknown',
backend: 'turso-wasm-opfs',
rolloutCohort: CACHE_ROLLOUT_COHORTS.includes(context.rolloutCohort)
? context.rolloutCohort
: 'unknown',
};
}
emit(input: CacheTelemetryObservation): void {
try {
const observation = sanitizeObservation(input);
if (!observation) return;
this.sink.emit(Object.freeze({ ...this.context, ...observation }));
} catch {
// Export failure cannot change request, transaction, or lifecycle state.
}
}
}
export const NOOP_CACHE_TELEMETRY: CacheTelemetryRecorderLike = Object.freeze({
record: () => undefined,
flush: () => undefined,
});
/** Wraps even an untrusted injected recorder in the correctness firewall. */
export function isolateCacheTelemetry(
recorder: CacheTelemetryRecorderLike | undefined
): CacheTelemetryRecorderLike {
if (!recorder) return NOOP_CACHE_TELEMETRY;
return {
record(observation): void {
try {
recorder.record(observation);
} catch {
// Injected sinks have the same failure-isolation contract as OTel.
}
},
flush(): void {
try {
recorder.flush();
} catch {
// Cleanup remains independent from exporter behavior.
}
},
};
}
export function operationCategoryForRequest(
request: Pick<CacheRequest, 'kind'>
): CacheOperationCategory {
return match(request.kind)
.with('init', () => 'initialization' as const)
.with(
'read',
'current-revision',
'read-records-by-keys',
'search',
'entity-filter',
'calendar-range',
() => 'read' as const
)
.with('write', 'hydrate', 'calendar-commit', () => 'write' as const)
.with(
'enqueue-optimistic-mutation',
'claim-next-mutation',
'defer-optimistic-write',
'commit-optimistic-write',
'rollback-optimistic-write',
() => 'transaction' as const
)
.with(
'inspect-query',
'inspect-query-variants',
() => 'inspection' as const
)
.with('invalidate', 'delete-records', () => 'invalidation' as const)
.with(
'teardown',
'clear',
'current-storage-generation',
'inspect-mutations',
() => 'lifecycle' as const
)
.exhaustive(() => 'lifecycle' as const);
}
export function isStorageTransactionRequest(
request: Pick<CacheRequest, 'kind'>
): boolean {
return [
'write',
'hydrate',
'calendar-commit',
'enqueue-optimistic-mutation',
'claim-next-mutation',
'defer-optimistic-write',
'commit-optimistic-write',
'rollback-optimistic-write',
'invalidate',
'delete-records',
'clear',
].includes(request.kind);
}
/** Classifies an error without retaining or exporting its message. */
export function classifyCacheError(error: unknown): CacheErrorCode {
const message =
error instanceof Error
? error.message.toLowerCase()
: typeof error === 'string'
? error.toLowerCase()
: '';
if (message.includes('timeout')) return 'timeout';
if (message.includes('quota') || /\bfull\b/.test(message))
return 'opfs-quota';
if (message.includes('opfs') && message.includes('unavailable')) {
return 'opfs-unavailable';
}
if (message.includes('opfs') || message.includes('wal')) return 'opfs-io';
if (message.includes('lock')) return 'lock';
if (message.includes('owner epoch') || message.includes('owner-lost')) {
return 'owner-lost';
}
if (message.includes('protocol') || message.includes('envelope')) {
return 'protocol';
}
if (message.includes('transport') || message.includes('messageport')) {
return 'transport';
}
if (message.includes('schema') || message.includes('namespace')) {
return 'schema';
}
if (message.includes('integrity') || message.includes('corrupt')) {
return 'integrity';
}
if (message.includes('reset required')) return 'storage-reset';
if (message.includes('wasm')) return 'wasm-instantiate';
if (message.includes('initializ') || message.includes('open')) {
return 'initialization';
}
return 'unknown';
}
export function resetReasonForError(error: unknown): CacheResetReason {
const code = classifyCacheError(error);
if (code === 'opfs-quota') return 'quota-failure';
if (code === 'integrity') return 'integrity-failure';
if (code === 'schema') return 'namespace-mismatch';
if (code === 'owner-lost') return 'abrupt-owner-loss';
return 'storage-reset-required';
}
export function browserCacheTelemetryContext(
rolloutCohort: CacheRolloutCohort,
userAgent = typeof navigator === 'undefined' ? '' : navigator.userAgent,
appVersion = import.meta.env.__APP_VERSION__ ?? 'unknown'
): CacheTelemetryContext {
const firefox = /Firefox\/(\d+(?:\.\d+)*)/i.exec(userAgent);
const chromium = /(?:Chrome|Chromium)\/(\d+(?:\.\d+)*)/i.exec(userAgent);
const safari =
/Safari\//i.test(userAgent) && !chromium
? /Version\/(\d+(?:\.\d+)*)/i.exec(userAgent)
: null;
const match = firefox ?? chromium ?? safari;
const browserFamily = firefox
? 'firefox'
: chromium
? 'chromium'
: safari
? 'safari'
: 'other';
const safeVersion = match?.[1]?.split('.')[0] ?? 'unknown';
const appRelease = /^(\d+)\.(\d+)/.exec(appVersion);
const safeAppVersion = appRelease
? `${appRelease[1]}.${appRelease[2]}`.slice(0, 16)
: 'unknown';
return {
browserFamily,
browserVersion: safeVersion,
appVersion: safeAppVersion,
backend: 'turso-wasm-opfs',
rolloutCohort: CACHE_ROLLOUT_COHORTS.includes(rolloutCohort)
? rolloutCohort
: 'unknown',
};
}
export function isCacheTelemetryObservation(
value: unknown
): value is CacheTelemetryObservation {
if (typeof value !== 'object' || value === null) return false;
const candidate = sanitizeObservation(value as CacheTelemetryObservation);
if (!candidate) return false;
return Object.keys(value).every((key) =>
[
'name',
'aggregatedEventName',
'operationCategory',
'outcome',
'errorCode',
'resetReason',
'ownerEvent',
'persistence',
'openOutcome',
'queueDiagnosticsAvailability',
'revisionCategory',
'resetAttempt',
'durationMs',
'queryFingerprint',
'bytes',
'highWaterBytes',
'usageBytes',
'quotaBytes',
'ratio',
'count',
'sampleRate',
'queueDepth',
'oldestAgeMs',
].includes(key)
);
}