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 type { IdentityBindingWire, MutationInspection } from '../protocol';
/**
* Typed surface of the generated wasm package (`cache-wasm`), loaded
* dynamically so the repo type-checks without the generated artifacts.
*
* Build the package with:
* just build-cache-wasm
* which runs wasm-pack over crates/client/cache-wasm into
* src/lib/graphql-cache/wasm/ (gitignored).
*/
import type { EntityResolverWire } from '../exchange/entity-resolvers';
import type {
AffectedOperationsResult,
CachedQueryInstanceWire,
CachedQueryVariantWire,
CacheRevision,
CacheRevisionResult,
CalendarCommitArgs,
CalendarRangeCacheArgs,
CalendarRangeCacheResult,
ClaimedMutation,
CommitOptimisticWriteResult,
DeferOptimisticWriteResult,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
EntityFilterCacheResult,
HydrationSearchChanges,
OptimisticLinkPatchWire,
QueryRevalidationWire,
ReadRecordsByKeysResult,
ReadResult,
RollbackOptimisticWriteResult,
SearchCacheArgs,
SearchCachePage,
WriteResult,
} from '../protocol';
import { workerCacheTelemetry } from '../telemetry-relay';
import type { StaleDatabaseRemovalOutcome } from './stale-databases';
/** Stable, payload-free marker latched on reset-required WASM errors. */
export interface CacheStorageResetRequiredError extends Error {
readonly cacheStorageResetRequired: true;
}
export type CacheOpenOutcome =
| 'opened-existing'
| 'opened-new'
| 'reset-incompatible'
| 'reset-corrupt'
| 'reset-storage-uncertain';
export type CacheQueueDiagnostics =
| {
availability: 'available';
/** Decimal strings preserve Rust integer precision across wasm-bindgen. */
depth: string;
oldestCreatedAtMs: string | null;
}
| {
/** Compatibility engines must never masquerade as an empty queue. */
availability: 'unavailable';
depth: null;
oldestCreatedAtMs: null;
};
export interface CacheOpenResult {
engine: CacheEngine;
outcome: CacheOpenOutcome;
}
export type CacheEngineHydrationResult = WriteResult &
HydrationSearchChanges & {
data: unknown | null;
};
export interface CacheEngine {
currentRevision(): Promise<CacheRevision>;
currentStorageGeneration(): Promise<string>;
boundIdentity(): Promise<string | null>;
/** Optional for compatibility engines; absence means unavailable. */
queueDiagnostics?(): Promise<CacheQueueDiagnostics>;
readQuery(
opId: string | undefined,
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
entityResolvers: readonly EntityResolverWire[] | undefined
): Promise<ReadResult>;
watchQuery?(
opId: string,
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
entityResolvers: readonly EntityResolverWire[] | undefined,
since: string | undefined
): Promise<import('../protocol').QueryUpdate>;
readRecordsByKeys(
document: string,
fragmentName: string,
keys: string[]
): Promise<ReadRecordsByKeysResult>;
search(
request: SearchCacheArgs & { nowMs: number }
): Promise<SearchCachePage>;
entityFilter(
request: EntityFilterCacheArgs
): Promise<EntityFilterCacheResult>;
calendarRange(
request: CalendarRangeCacheArgs
): Promise<CalendarRangeCacheResult>;
/** Resolves like `writeQuery`: deleted records are reported as `changed`. */
calendarCommit(commit: CalendarCommitArgs): Promise<WriteResult>;
writeQuery(
context: {
originOpId?: string;
registration?: {
opId: string;
entityResolvers?: readonly EntityResolverWire[];
};
},
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
data: unknown,
identity: string | undefined
): Promise<WriteResult>;
hydrateQuery(
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
data: unknown,
identity: string | undefined
): Promise<CacheEngineHydrationResult>;
inspectMutations(): Promise<MutationInspection[]>;
enqueueOptimisticMutation(
originOpId: string | undefined,
uuid: string,
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
data: unknown,
linkPatches: OptimisticLinkPatchWire[] | undefined,
revalidations: QueryRevalidationWire[] | undefined,
identityBindings: IdentityBindingWire[] | undefined,
createdAtMs: number,
leaseOwner: string,
nowMs: number,
leaseExpiresAtMs: number,
clientMetadata?: Record<string, unknown>,
uncertainCalendarEventKeys?: string[]
): Promise<EnqueueOptimisticMutationResult>;
inspectQueryVariants(
query: string,
operationName: string | undefined,
path: Array<{ field: string }>
): Promise<CachedQueryVariantWire[]>;
inspectQuery(
query: string,
operationName: string | undefined,
path: Array<{ field: string }>,
variableFilters: Array<Record<string, unknown>>
): Promise<CachedQueryInstanceWire[]>;
claimNextMutation(
owner: string,
nowMs: number,
leaseExpiresAtMs: number
): Promise<ClaimedMutation | undefined>;
deferOptimisticWrite(
transactionId: string,
leaseOwner: string,
leaseGeneration: string,
nextAttemptAtMs: number,
error: string,
serverFailure: boolean
): Promise<DeferOptimisticWriteResult>;
commitOptimisticWrite(
transactionId: string,
leaseOwner: string,
leaseGeneration: string,
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
data: unknown
): Promise<CommitOptimisticWriteResult>;
rollbackOptimisticWrite(
transactionId: string,
leaseOwner: string,
leaseGeneration: string
): Promise<RollbackOptimisticWriteResult>;
invalidateKeys(keys: string[]): Promise<AffectedOperationsResult>;
deleteKeys(keys: string[]): Promise<AffectedOperationsResult>;
teardownOperation(opId: string): Promise<void>;
clear(): Promise<CacheRevisionResult>;
/** Reset/recreate OPFS; concurrent calls wait for the fresh engine. */
physicalReset(): Promise<void>;
/** Gracefully close Turso/OPFS and release the owner lock. */
close(): Promise<void>;
}
export interface CacheWasmModule {
default: (input?: { module_or_path?: unknown }) => Promise<unknown>;
openCache(scope: string, hotCapacity?: number): Promise<CacheEngine>;
/**
* Additive open API with a coarse, payload-free recovery outcome. When
* given, `onOwnerLockAcquired` runs after the owner lock is held and before
* any OPFS access; opening continues once its promise resolves. With
* `ifAvailable`, a held owner lock rejects at once, touching nothing, with an
* error whose `cacheOwnerLockUnavailable` property is `true`. Files another
* context keeps open through a bounded wait reject with an error whose
* `cacheStorageBusy` property is `true`; a plain open has then changed
* neither file.
*/
openCacheWithOutcome?(
scope: string,
hotCapacity?: number,
onOwnerLockAcquired?: () => Promise<void>,
ifAvailable?: boolean
): Promise<CacheOpenResult>;
/** Atomically wipes before Turso open while retaining one OPFS owner lock. */
openCacheForRecovery(
scope: string,
hotCapacity?: number
): Promise<CacheEngine>;
/** Additive recovery-open API with its coarse wipe outcome; see above for
* `onOwnerLockAcquired` and `ifAvailable`, which precede the recovery wipe. */
openCacheForRecoveryWithOutcome?(
scope: string,
hotCapacity?: number,
onOwnerLockAcquired?: () => Promise<void>,
ifAvailable?: boolean
): Promise<CacheOpenResult>;
destroyCache(scope: string): Promise<void>;
/** Physical database this build opens for `scope`; absent before databases
* were named by storage version. */
cacheDatabaseIdentity?(scope: string): string;
/** Deletes one stale database of `scope` if unused and without queued
* mutations; see `staleCacheDatabaseIdentities`. */
removeStaleCacheDatabase?(
scope: string,
identity: string
): Promise<StaleDatabaseRemovalOutcome>;
/** Optional while older cached WASM artifacts are still in circulation. */
setSlowQueryCallback?(
callback: (
fingerprint: string,
durationMs: number,
success: boolean
) => void
): void;
/** Installs the schema shipped with this frontend before opening storage. */
configureCacheSchema(schemaSdl: string): void;
schemaHash(): string;
/** Read-only binary metadata; optional so fixtures can diagnose stale artifacts. */
cacheBuildInfo?(): unknown;
}
let modulePromise: Promise<CacheWasmModule> | undefined;
let wasmMemory: WebAssembly.Memory | undefined;
/** Returns the combined module's current unshared linear-memory allocation. */
export function cacheWasmLinearMemoryBytes(): number {
if (!wasmMemory) throw new Error('cache WASM memory is not initialized');
return wasmMemory.buffer.byteLength;
}
/** Loads and initializes the wasm module exactly once per worker context. */
export function loadCacheWasm(): Promise<CacheWasmModule> {
if (!modulePromise) {
const initialization = (async () => {
const telemetry = workerCacheTelemetry();
const now = (): number => globalThis.performance?.now() ?? Date.now();
const url = new URL('../wasm/cache_wasm.js', import.meta.url).href;
const mod = (await import(/* @vite-ignore */ url)) as CacheWasmModule;
// Resolve the wasm binary explicitly: vite copies the generated JS as
// an opaque asset, so its internal relative `cache_wasm_bg.wasm` URL
// would 404 in production. This `new URL` pattern is statically
// analyzable, so vite emits exactly one lazy hashed binary. Explicit
// fetch/compile keeps download, compile, and instantiate separately observable.
const wasmUrl = new URL('../wasm/cache_wasm_bg.wasm', import.meta.url);
const downloadStartedAt = now();
let bytes: ArrayBuffer;
try {
const response = await fetch(wasmUrl);
if (!response.ok) {
throw new Error(
`cache WASM download returned HTTP ${response.status}`
);
}
bytes = await response.arrayBuffer();
telemetry.record({
name: 'graphql_cache.wasm_download',
operationCategory: 'initialization',
outcome: 'success',
errorCode: 'none',
durationMs: now() - downloadStartedAt,
bytes: bytes.byteLength,
});
} catch (error) {
telemetry.record({
name: 'graphql_cache.wasm_download',
operationCategory: 'initialization',
outcome: 'error',
errorCode: 'wasm-download',
durationMs: now() - downloadStartedAt,
});
throw error;
}
const compileStartedAt = now();
let compiled: WebAssembly.Module;
try {
compiled = await WebAssembly.compile(bytes);
telemetry.record({
name: 'graphql_cache.wasm_compile',
operationCategory: 'initialization',
outcome: 'success',
errorCode: 'none',
durationMs: now() - compileStartedAt,
});
} catch (error) {
telemetry.record({
name: 'graphql_cache.wasm_compile',
operationCategory: 'initialization',
outcome: 'error',
errorCode: 'wasm-compile',
durationMs: now() - compileStartedAt,
});
throw error;
}
const instantiateStartedAt = now();
try {
const exports = (await mod.default({ module_or_path: compiled })) as {
memory?: WebAssembly.Memory;
};
if (!(exports.memory instanceof WebAssembly.Memory)) {
throw new Error('cache WASM did not export its linear memory');
}
const { default: schemaSdl } = await import(
'../../../../../../static_assets/schema.graphql?raw'
);
mod.configureCacheSchema(schemaSdl);
wasmMemory = exports.memory;
mod.setSlowQueryCallback?.((queryFingerprint, durationMs, success) => {
telemetry.record({
name: 'graphql_cache.slow_query',
operationCategory: 'storage',
queryFingerprint,
durationMs,
outcome: success ? 'success' : 'error',
});
});
telemetry.record({
name: 'graphql_cache.wasm_instantiate',
operationCategory: 'initialization',
outcome: 'success',
errorCode: 'none',
durationMs: now() - instantiateStartedAt,
});
return mod;
} catch (error) {
telemetry.record({
name: 'graphql_cache.wasm_instantiate',
operationCategory: 'initialization',
outcome: 'error',
errorCode: 'wasm-instantiate',
durationMs: now() - instantiateStartedAt,
});
throw error;
}
})();
modulePromise = initialization;
void initialization.catch(() => {
if (modulePromise === initialization) modulePromise = undefined;
});
}
return modulePromise;
}