Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

37.5 KB
Raw Blame
/** Explicit local entities resolved atomically from a committed mutation response. */
export type IdentityBindingWire = {
  deleteRecord?: boolean;
  localKey: string;
  responsePath: string[];
  referenceFields?: string[];
  revalidationVariables?: string[];
};

import type { EntityResolverWire } from './exchange/entity-resolvers';

/**
 * Wire protocol between page contexts and the cache worker (the `CacheHost`
 * RPC from the design doc, apps/web/docs/graphql-normalized-cache-plan.md §4).
 *
 * The browser topology routes page ports through a SharedWorker coordinator
 * to one elected DedicatedWorker engine. Platforms missing the required
 * coordinator capabilities use a storage-free no-op host.
 *
 * Operation ids are strings of the form `"{clientId}:{urqlOperationKey}"` so
 * one shared engine can track operations from many tabs without collisions.
 */

export type ReadResult = { kind: 'hit'; data: unknown } | { kind: 'miss' };

/** Paths come from the schema-aware engine projection, including aliases. */
export type QueryFieldPatch = { path: (string | number)[]; value: unknown };
export type QueryUpdate =
  | { kind: 'hit'; data: unknown; revision: CacheRevision }
  | { kind: 'patch'; patches: QueryFieldPatch[]; revision: CacheRevision }
  | { kind: 'miss'; revision: CacheRevision }
  | { kind: 'unsupported' };

/** Opaque in-memory revision of one live cache engine generation. */
export type CacheRevision = string & {
  readonly __cacheRevision: unique symbol;
};

const MAX_CACHE_REVISION = 18_446_744_073_709_551_615n;

/** Validates the canonical unsigned-decimal Rust `u64` wire representation. */
export function isCacheRevision(value: unknown): value is CacheRevision {
  return (
    typeof value === 'string' &&
    /^(0|[1-9][0-9]*)$/.test(value) &&
    BigInt(value) <= MAX_CACHE_REVISION
  );
}

/** Parses an untrusted cache revision at protocol ingress. */
export function parseCacheRevision(value: unknown): CacheRevision {
  if (!isCacheRevision(value)) {
    throw new TypeError('invalid cache revision');
  }
  return value;
}

export const INITIAL_CACHE_REVISION = '0' as CacheRevision;

/** Validates the durable database-generation UUID shared by cache hosts. */
export function parseStorageGeneration(value: unknown): string {
  if (
    typeof value !== 'string' ||
    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(
      value
    )
  ) {
    throw new TypeError('invalid cache storage generation');
  }
  return value;
}

/** Scheduling hint for latency-sensitive cache reads. */
export type CacheReadPriority = 'user-visible';

/** Recursive partial-variable object used to limit query inspection work. */
export type QueryVariableFilter = Record<string, unknown>;

export type SearchProfile = 'quick-access-v1';

export type SearchCursor = {
  timestampMs: number;
  recordKey: string;
};

export type SearchDocumentWire = {
  profile: SearchProfile;
  recordKey: string;
  bucket: string;
  searchText: string;
  timestampMs: number;
  sourceHash: string;
};

export type SearchCacheArgs = {
  profile: SearchProfile;
  buckets?: string[];
  query?: string;
  cursor?: SearchCursor;
  limit: number;
  /** Injected for deterministic freshness scoring. Defaults to Date.now(). */
  nowMs?: number;
};

export type SearchCachePage = {
  documents: SearchDocumentWire[];
  nextCursor: SearchCursor | null;
};

/** Maximum server-page membership evidence in one reconciliation request. */
export const MAX_RECONCILIATION_BASELINE = 5_000;

/** Initial-page candidates, optionally reconciled with same-query server pages. */
export type EntityFilterCacheArgs = {
  /** Opt into an engine-maintained fragment view and incremental results. */
  liveQuery?: {
    id: string;
    document: string;
    fragmentName: string;
    since?: CacheRevision;
    release?: boolean;
  };
  filters: Record<string, unknown>;
  sortMethod: 'CREATED_AT' | 'UPDATED_AT' | 'VIEWED_AT' | 'VIEWED_UPDATED';
  sortDirection: 'ASC' | 'DESC';
  limit: number;
  /** Omit for exact evaluation; even an empty array requests reconciliation. */
  baseline?: Array<{ key: string; sortTimestamp: string }>;
  /** Explicit cached-Mail pagination, independent of server cursors. */
  mail?: {
    view: 'ALL' | 'INBOX' | 'DRAFTS' | 'SENT';
    /** Continue after this row. Valid across writes; not with `through`. */
    cursor?: string;
    /** A page's `endCursor`: read from the top through that row instead of `limit` rows. */
    through?: string;
  };
};

export type EntityFilterCacheResult =
  | LiveQueryUpdate
  | {
      kind: 'mail-page';
      /** Complete engine-owned window; absent on older native runtimes. */
      observationId?: string;
      revision: CacheRevision;
      keys: string[];
      /** Server members with incomplete local metadata; absent on older native hosts. */
      retainedKeys?: string[];
      /** View-correct timestamps aligned with keys, independent of cached previews. */
      sortTimestamps: string[];
      nextCursor: string | null;
      /** Position of the last row. Absent from native engines that predate `through`. */
      endCursor?: string | null;
      optimistic: boolean;
    }
  /** The cursor's engine generation or query changed; on native engines that predate `through`, any write. */
  | { kind: 'stale-cursor'; revision: CacheRevision }
  | {
      kind: 'reconciled';
      revision: CacheRevision;
      keys: string[];
      /** Survivors backed only by previous server membership evidence. */
      retainedKeys: string[];
      optimistic: boolean;
    }
  | {
      kind: 'complete';
      revision: CacheRevision;
      keys: string[];
      optimistic: boolean;
    }
  | { kind: 'unsupported' }
  | { kind: 'incomplete'; revision: CacheRevision };

export type LiveQueryUpdate = {
  kind: 'live-query';
  /** Native specification identity; absent from older installed binaries. */
  registrationId?: string;
  /** Immutable observation of this exact evaluated window; legacy hosts omit it. */
  observationId?: string;
  revision: CacheRevision;
  reset: boolean;
  /** Omitted when the existing order remains valid. */
  keys?: string[];
  upserts: SelectedRecordByKeyWire[];
  patches: Array<{
    recordKey: string;
    fields: Array<{ path: Array<string | number>; value: unknown }>;
    identity: { mutationUuid: string | null; pending: boolean };
  }>;
  removed: string[];
  retainedKeys: string[];
  optimistic: boolean;
};

/** Unit of a calendar span: UTC milliseconds, or local days since 1970-01-01. */
export type CalendarSpanKind = 'timed' | 'allDay';

/** Half-open `[start, end)` calendar span. */
export type CalendarSpanWire = {
  kind: CalendarSpanKind;
  start: number;
  end: number;
};

/** Applied change-log position of one email link; `seq` is a decimal i64. */
export type CalendarLinkWatermarkWire = { linkId: string; seq: string };

export type CalendarFreshness = 'fresh' | 'stale' | 'unknown';

/**
 * One calendar viewport over both span kinds. Empty spans read only the sync
 * state (freshness and watermark).
 */
export type CalendarRangeCacheArgs = {
  startMs: number;
  endMs: number;
  startDay: number;
  endDay: number;
  /** Restricts occurrences to one `GraphqlCalendarEvent:{id}` key. */
  eventKey?: string;
};

export type CalendarRangeCacheResult =
  | {
      kind: 'range';
      revision: CacheRevision;
      /** `GraphqlCalendarOccurrence` keys ordered by kind, start, and key. */
      occurrenceKeys: string[];
      /** Requested spans never fetched from the server. */
      gaps: CalendarSpanWire[];
      freshness: CalendarFreshness;
      /** Events whose occurrence set is unknown until a pending mutation settles. */
      uncertainEventKeys: string[];
      /** Whether a pending optimistic mutation shaped this result. */
      optimistic: boolean;
      /** Null until a commit carries a watermark. */
      watermark: CalendarLinkWatermarkWire[] | null;
    }
  /** The native host predates calendar ranges; read calendars from the network. */
  | { kind: 'unsupported' };

/**
 * `merge` lowers each link to a page's pre-read watermark; `advance` moves
 * links still at `since` to the delta's `to` and keeps concurrent lowerings.
 */
export type CalendarWatermarkUpdateWire =
  | { kind: 'merge'; links: CalendarLinkWatermarkWire[] }
  | {
      kind: 'advance';
      since: CalendarLinkWatermarkWire[];
      to: CalendarLinkWatermarkWire[];
    };

/** One atomic change to calendar coverage, cached calendar records, and sync state. */
export type CalendarCommitArgs = {
  /** Spans whose occurrences were fully fetched and written. */
  coverage?: CalendarSpanWire[];
  /** Events whose cached occurrences outside `occurrenceKeys` are deleted. */
  replacedEvents?: Array<{ eventKey: string; occurrenceKeys: string[] }>;
  /** Events deleted with every cached occurrence. */
  deletedEventKeys?: string[];
  deletedCalendarKeys?: string[];
  /** Links no longer visible: their occurrences, events, and calendars are deleted. */
  removedLinkIds?: string[];
  watermark?: CalendarWatermarkUpdateWire;
  freshness?: 'fresh' | 'stale';
  /** Deletes every cached occurrence, event, coverage span, and the watermark first. */
  reset?: boolean;
};

export type CalendarCommitCacheResult =
  | {
      kind: 'committed';
      revision: CacheRevision;
      /** Records the commit deleted. */
      changed: string[];
    }
  | { kind: 'unsupported' };

export type ReadRecordsByKeysArgs = {
  /** Serialized generated fragment document. */
  document: string;
  /** Root fragment to apply to the requested normalized records. */
  fragmentName: string;
  /** Canonical normalized entity keys; bounded by the selection page size. */
  keys: string[];
};

export type SelectedRecordByKeyWire = {
  identity?: { mutationUuid: string | null; pending: boolean };
  recordKey: string;
  record: unknown;
};

export type ReadRecordsByKeysResult = {
  revision: CacheRevision;
  records: SelectedRecordByKeyWire[];
};

export type AffectedOperationsResult = {
  revision: CacheRevision;
  affectedOps: string[];
};

export type CacheRevisionResult = {
  revision: CacheRevision;
};

export const MAX_RECORD_SELECTION_PAGE_SIZE = 500;
/** The most rows a Mail read `through` a position returns, as the engine caps it. */
export const MAX_MAIL_THROUGH_ROWS = 5_000;
export const MAX_CACHE_SEARCH_QUERY_BYTES = 512;
export const MAX_NORMALIZED_RECORD_KEY_LENGTH = 1024;

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === 'object' && value !== null && !Array.isArray(value);

/** Non-throwing canonical normalized-record key validation for wire ingress. */
export function isValidNormalizedRecordKey(value: unknown): value is string {
  return (
    typeof value === 'string' &&
    value.length <= MAX_NORMALIZED_RECORD_KEY_LENGTH &&
    /^[A-Za-z_][A-Za-z0-9_]*:/.test(value)
  );
}

/** Non-throwing cache-search profile validation for wire ingress. */
export function isValidCacheSearchProfile(
  value: unknown
): value is SearchProfile {
  return value === 'quick-access-v1';
}

/** Non-throwing cache-search limit validation for wire ingress. */
export function isValidCacheSearchLimit(value: unknown): value is number {
  return (
    Number.isSafeInteger(value) &&
    (value as number) >= 1 &&
    (value as number) <= MAX_RECORD_SELECTION_PAGE_SIZE
  );
}

/** Non-throwing cache-search query validation for wire ingress. */
export function isValidCacheSearchQuery(value: unknown): value is string {
  return (
    typeof value === 'string' &&
    new TextEncoder().encode(value).length <= MAX_CACHE_SEARCH_QUERY_BYTES
  );
}

/** Non-throwing cache-search bucket validation for wire ingress. */
export function isValidCacheSearchBucket(value: unknown): value is string {
  return typeof value === 'string' && /^[a-z_]{1,64}$/.test(value);
}

/** Non-throwing cache-search clock validation for wire ingress. */
export function isValidCacheSearchNowMs(value: unknown): value is number {
  return Number.isSafeInteger(value) && (value as number) >= 0;
}

/** Non-throwing cache-search cursor validation for wire ingress. */
export function isValidCacheSearchCursor(
  value: unknown
): value is SearchCursor {
  return (
    isRecord(value) &&
    Object.keys(value).every(
      (key) => key === 'timestampMs' || key === 'recordKey'
    ) &&
    Object.hasOwn(value, 'timestampMs') &&
    Object.hasOwn(value, 'recordKey') &&
    Number.isSafeInteger(value.timestampMs) &&
    isValidNormalizedRecordKey(value.recordKey)
  );
}

const hasOnlyCalendarKeys = (
  value: Record<string, unknown>,
  keys: readonly string[]
): boolean => Object.keys(value).every((key) => keys.includes(key));

const isCalendarSpanWire = (value: unknown): value is CalendarSpanWire =>
  isRecord(value) &&
  hasOnlyCalendarKeys(value, ['kind', 'start', 'end']) &&
  (value.kind === 'timed' || value.kind === 'allDay') &&
  Number.isSafeInteger(value.start) &&
  Number.isSafeInteger(value.end);

const isCalendarWatermarkWire = (
  value: unknown
): value is CalendarLinkWatermarkWire[] =>
  Array.isArray(value) &&
  value.every(
    (link) =>
      isRecord(link) &&
      hasOnlyCalendarKeys(link, ['linkId', 'seq']) &&
      typeof link.linkId === 'string' &&
      link.linkId.length > 0 &&
      typeof link.seq === 'string' &&
      /^[0-9]{1,19}$/.test(link.seq)
  );

const isOptionalWireArray = (
  value: unknown,
  item: (entry: unknown) => boolean
): boolean =>
  value === undefined || (Array.isArray(value) && value.every(item));

const isCalendarWatermarkUpdateWire = (value: unknown): boolean =>
  isRecord(value) &&
  ((value.kind === 'merge' &&
    hasOnlyCalendarKeys(value, ['kind', 'links']) &&
    isCalendarWatermarkWire(value.links)) ||
    (value.kind === 'advance' &&
      hasOnlyCalendarKeys(value, ['kind', 'since', 'to']) &&
      isCalendarWatermarkWire(value.since) &&
      isCalendarWatermarkWire(value.to)));

/** Non-throwing calendar range validation for wire ingress. */
export function isValidCalendarRangeArgs(
  value: unknown
): value is CalendarRangeCacheArgs {
  return (
    isRecord(value) &&
    hasOnlyCalendarKeys(value, [
      'startMs',
      'endMs',
      'startDay',
      'endDay',
      'eventKey',
    ]) &&
    Number.isSafeInteger(value.startMs) &&
    Number.isSafeInteger(value.endMs) &&
    Number.isSafeInteger(value.startDay) &&
    Number.isSafeInteger(value.endDay) &&
    (value.startMs as number) <= (value.endMs as number) &&
    (value.startDay as number) <= (value.endDay as number) &&
    (value.eventKey === undefined || isValidNormalizedRecordKey(value.eventKey))
  );
}

/**
 * Non-throwing calendar commit shape validation for wire ingress. The engine
 * still validates typenames, duplicates, and size bounds.
 */
export function isValidCalendarCommitArgs(
  value: unknown
): value is CalendarCommitArgs {
  return (
    isRecord(value) &&
    hasOnlyCalendarKeys(value, [
      'coverage',
      'replacedEvents',
      'deletedEventKeys',
      'deletedCalendarKeys',
      'removedLinkIds',
      'watermark',
      'freshness',
      'reset',
    ]) &&
    isOptionalWireArray(value.coverage, isCalendarSpanWire) &&
    isOptionalWireArray(
      value.replacedEvents,
      (event) =>
        isRecord(event) &&
        hasOnlyCalendarKeys(event, ['eventKey', 'occurrenceKeys']) &&
        isValidNormalizedRecordKey(event.eventKey) &&
        Array.isArray(event.occurrenceKeys) &&
        event.occurrenceKeys.every(isValidNormalizedRecordKey)
    ) &&
    isOptionalWireArray(value.deletedEventKeys, isValidNormalizedRecordKey) &&
    isOptionalWireArray(
      value.deletedCalendarKeys,
      isValidNormalizedRecordKey
    ) &&
    isOptionalWireArray(
      value.removedLinkIds,
      (linkId) => typeof linkId === 'string' && linkId.length > 0
    ) &&
    (value.watermark === undefined ||
      isCalendarWatermarkUpdateWire(value.watermark)) &&
    (value.freshness === undefined ||
      value.freshness === 'fresh' ||
      value.freshness === 'stale') &&
    (value.reset === undefined || typeof value.reset === 'boolean')
  );
}

export function validateRecordSelectionKeys(keys: string[]): string[] {
  if (keys.length > MAX_RECORD_SELECTION_PAGE_SIZE) {
    throw new RangeError(
      `record selection accepts at most ${MAX_RECORD_SELECTION_PAGE_SIZE} keys`
    );
  }
  if (keys.some((key) => !isValidNormalizedRecordKey(key))) {
    throw new RangeError('invalid normalized record key');
  }
  return keys;
}

export function validateCacheSearchArgs(
  args: SearchCacheArgs
): SearchCacheArgs & { nowMs: number } {
  if (!isValidCacheSearchProfile(args.profile)) {
    throw new RangeError('invalid cache search profile');
  }
  if (!isValidCacheSearchLimit(args.limit)) {
    throw new RangeError(
      `cache search limit must be an integer between 1 and ${MAX_RECORD_SELECTION_PAGE_SIZE}`
    );
  }
  const query = args.query === undefined ? '' : args.query;
  if (!isValidCacheSearchQuery(query)) {
    throw new RangeError('cache search query is too long');
  }
  const buckets = args.buckets === undefined ? [] : args.buckets;
  if (
    !Array.isArray(buckets) ||
    buckets.some((bucket) => !isValidCacheSearchBucket(bucket))
  ) {
    throw new RangeError('invalid cache search bucket');
  }
  const nowMs = args.nowMs === undefined ? Date.now() : args.nowMs;
  if (!isValidCacheSearchNowMs(nowMs)) {
    throw new RangeError('invalid cache search nowMs');
  }
  if (args.cursor !== undefined && !isValidCacheSearchCursor(args.cursor)) {
    throw new RangeError('invalid cache search cursor');
  }
  return {
    ...args,
    query,
    buckets,
    nowMs,
  };
}

export type QueryRevalidationWire = {
  query: string;
  operationName?: string;
  /** Run only if the mutation's relation recipes could not all be applied. */
  onlyOnLinkFailure?: boolean;
  /** Canonical JSON object, kept as text in the durable queue. */
  variablesJson: string;
};

export type EmbeddedLinkPathSegment =
  | { field: string }
  | {
      listItem: {
        whereField: string;
        equals: string | number | boolean | null;
      };
    };

export type OptimisticLinkPatchWire = {
  /** Generated query, or fragment document when recordRoot is present. */
  query: string;
  operationName?: string;
  /** Explicit normalized parent; absent for legacy query-rooted recipes. */
  recordRoot?: { fragmentName: string; entityKey: string };
  /** Variables for the entrypoint operation. */
  variablesJson: string;
  /** Response-key path beginning at the query root. */
  path: EmbeddedLinkPathSegment[];
  operation:
    | { kind: 'remove'; entityKey: string }
    | { kind: 'prependUnique'; entityKey: string }
    | {
        kind: 'upsertByField';
        entityKey: string;
        whereField: string;
        equals: string | number | boolean | null;
      }
    | {
        kind: 'removeEmbeddedLink';
        listItem: {
          whereField: string;
          equals: string | number | boolean | null;
        };
        linkField: string;
        countField: string;
        entityKey: string;
      }
    | {
        kind: 'upsertEmbeddedLink';
        listItem: {
          whereField: string;
          equals: string | number | boolean | null;
        };
        linkField: string;
        countField: string;
        entityKey: string;
        /** Scalar fields used only when the embedded item must be created. */
        insertFields: Record<string, string | number | boolean | null>;
      };
};

export type CachedQueryVariantWire = {
  variables: Record<string, unknown>;
};

export type CachedQueryInstanceWire = CachedQueryVariantWire & {
  /** Selected value; omitted when the reconstructed query is a cache miss. */
  value?: unknown;
};

/** Optional engine evidence. Missing fields preserve conservative invalidation. */
export type CacheChangeHints = {
  /** Windows proven unchanged. Missing IDs mean unknown, never unchanged. */
  unchangedViews?: string[];
  /** Known changed Quick Access buckets; [] proves no search change. */
  searchChangedBuckets?: string[];
};

/** Previous name, kept until the cache worker adopts CacheChangeHints. */
export type HydrationSearchChanges = CacheChangeHints;

export type HydrationResult = CacheChangeHints &
  (
    | { kind: 'data'; data: unknown; revision: CacheRevision }
    | { kind: 'void'; revision: CacheRevision }
  );

export type RecordFieldChange =
  | {
      kind: 'fields';
      key: string;
      fields: Record<string, string | number | boolean | null>;
    }
  | { kind: 'invalidate'; key: string };

export type WriteResult = CacheChangeHints & {
  /** Effective view changes. Missing metadata requires a conservative reread. */
  fieldChanges?: RecordFieldChange[];
  /** Bindings omitted while committing an otherwise normalizable response. */
  identityErrors?: string[];
  mutationUuid?: string;
  /** Effective-view revision installed by this logical mutation. */
  revision: CacheRevision;
  /** Whether this write advanced `revision`. */
  revisionAdvanced: boolean;
  /** Entity keys whose records changed. */
  changed: string[];
  /** Registered operation ids affected by the change (origin excluded). */
  affectedOps: string[];
  /**
   * True when the identity witness observed a different user and the cache
   * silently restarted (wiped + rebound) before this write. `affectedOps`
   * then contains every registered operation except the origin.
   */
  reset: boolean;
  /** Recovery queries for terminal settlement; skip superseded outcomes. */
  revalidations?: QueryRevalidationWire[];
};

/**
 * Result of installing an optimistic layer. `changed`/`affectedOps` reflect
 * *visible* (composed-view) changes — nothing is durable until the
 * transaction commits.
 */
export type OptimisticWriteResult = WriteResult & {
  /** Engine-assigned id; settle after claiming the queue head. */
  transactionId: string;
};

/** How a caller UUID changed the durable queue. */
export type MutationUpsertKind =
  | { kind: 'inserted' }
  | { kind: 'replaced-pending'; removedTransactionId: string }
  | { kind: 'appended-after-active'; activeTransactionId: string };

/** Read-only request snapshot; never contains a settlement lease token. */
export type MutationInspection = Pick<
  ClaimedMutation,
  | 'transactionId'
  | 'uuid'
  | 'superseded'
  | 'query'
  | 'operationName'
  | 'variables'
  | 'clientMetadata'
  | 'enqueuedAtMs'
> & { optimisticData: unknown };

/** Claimed strict queue head, ready to be forwarded through urql. */
export type ClaimedMutation = {
  clientMetadata?: Record<string, unknown> | null;
  transactionId: string;
  uuid: string;
  superseded: boolean;
  /** Must recover a server identity before a newer edit/discard can run. */
  requiresConfirmation: boolean;
  leaseGeneration: string;
  query: string;
  operationName?: string;
  variables: Record<string, unknown>;
  /** Identity witness captured at enqueue time. */
  identity?: string;
  attemptCount: number;
  /** Retryable server failures; transport failures do not consume this budget. */
  serverFailureCount: number;
  /**
   * Durable first-enqueue wall-clock time in epoch ms, kept when a write
   * replaces an unsent one for the same UUID. Native claims and hosts built
   * before this field omit it, so it is unknown rather than zero.
   */
  enqueuedAtMs?: number;
};

/** Outcome of the strict-head claim attempted immediately after enqueue. */
export type InitialMutationClaim =
  | { kind: 'claimed'; mutation: ClaimedMutation }
  | { kind: 'not-runnable' }
  | { kind: 'failed'; error: string };

/** Result returned after enqueue and the initial claim attempt complete. */
export type EnqueueOptimisticMutationResult = OptimisticWriteResult & {
  upsertKind: MutationUpsertKind;
  initialClaim: InitialMutationClaim;
};

/** Identifies the queue attempt allowed to settle a transaction. */
export type MutationClaim = {
  owner: string;
  generation: string;
};

/** Result of deferring a retryable attempt. */
export type DeferOptimisticWriteResult =
  | { kind: 'deferred' }
  | (WriteResult & {
      kind: 'discarded-superseded';
      replacementTransactionId: string;
    });

/** Result of committing a current or superseded attempt. */
export type CommitOptimisticWriteResult =
  | (WriteResult & {
      kind: 'failed';
      error: string;
      replacementTransactionId?: string;
    })
  | (WriteResult & { kind: 'committed' })
  | (WriteResult & {
      kind: 'committed-superseded';
      replacementTransactionId: string;
    });

/** Result of rolling back a failed attempt. */
export type RollbackOptimisticWriteResult =
  | (WriteResult & { kind: 'rolled-back' })
  | (WriteResult & {
      kind: 'discarded-superseded';
      replacementTransactionId: string;
    });

/** Final settlement of a previously queued optimistic mutation. */
export type MutationSettlement = { mutationUuid?: string } & (
  | { transactionId: string; status: 'committed' }
  | {
      transactionId: string;
      status: 'superseded';
      replacementTransactionId: string;
    }
  | {
      transactionId: string;
      status: 'permanently-failed';
      error: string;
      errorCode?: string;
    }
);

export type CacheRequest = { id: number } & (
  | { kind: 'init'; scope: string; hotCapacity?: number }
  | { kind: 'current-revision' }
  | { kind: 'current-storage-generation' }
  | { kind: 'inspect-mutations' }
  | {
      kind: 'read';
      /** Incremental projection; requires a namespaced operation id. */
      watch?: { since?: CacheRevision };
      opId?: string;
      query: string;
      operationName?: string;
      variables?: Record<string, unknown>;
      /** May overtake unrelated observational reads, never ordering barriers. */
      priority?: CacheReadPriority;
      /** Per-read synthetic entity relations. */
      entityResolvers?: readonly EntityResolverWire[];
    }
  | {
      kind: 'write';
      originOpId?: string;
      registration?: {
        opId: string;
        entityResolvers?: readonly EntityResolverWire[];
      };
      query: string;
      operationName?: string;
      variables?: Record<string, unknown>;
      data: unknown;
      /**
       * Opaque session tag (e.g. viewer id extracted from the response). A
       * write tagged with a different identity than the cache's bound one
       * wipes and rebinds the cache atomically (silent restart).
       */
      identity?: string;
    }
  | {
      /** Background cache warming; ordinary writes do not publish pushes. */
      kind: 'hydrate';
      query: string;
      operationName?: string;
      variables?: Record<string, unknown>;
      data: unknown;
      identity?: string;
    }
  /** Durably enqueue an optimistic mutation and claim the strict head. */
  | {
      kind: 'enqueue-optimistic-mutation';
      originOpId?: string;
      uuid: string;
      query: string;
      operationName?: string;
      variables?: Record<string, unknown>;
      data: unknown;
      linkPatches?: OptimisticLinkPatchWire[];
      revalidations?: QueryRevalidationWire[];
      clientMetadata?: Record<string, unknown>;
      identityBindings?: IdentityBindingWire[];
      uncertainCalendarEventKeys?: string[];
      createdAtMs: number;
      owner: string;
      nowMs: number;
      leaseExpiresAtMs: number;
    }
  | {
      kind: 'claim-next-mutation';
      owner: string;
      nowMs: number;
      leaseExpiresAtMs: number;
    }
  | {
      kind: 'defer-optimistic-write';
      transactionId: string;
      leaseOwner: string;
      leaseGeneration: string;
      nextAttemptAtMs: number;
      error: string;
      serverFailure?: boolean;
    }
  /** Atomically replace a claimed layer with the real network response. */
  | {
      kind: 'commit-optimistic-write';
      transactionId: string;
      leaseOwner: string;
      leaseGeneration: string;
      query: string;
      operationName?: string;
      variables?: Record<string, unknown>;
      data: unknown;
    }
  /** Drop a claimed layer's contribution (permanent mutation failure). */
  | {
      kind: 'rollback-optimistic-write';
      transactionId: string;
      leaseOwner: string;
      leaseGeneration: string;
      error: string;
      errorCode?: string;
    }
  | {
      kind: 'read-records-by-keys';
      document: string;
      fragmentName: string;
      keys: string[];
    }
  | {
      kind: 'search';
      request: SearchCacheArgs & { nowMs: number };
    }
  | {
      kind: 'entity-filter';
      request: EntityFilterCacheArgs;
    }
  | {
      kind: 'calendar-range';
      request: CalendarRangeCacheArgs;
    }
  /** Atomically apply calendar coverage, deletions, and sync state. */
  | {
      kind: 'calendar-commit';
      commit: CalendarCommitArgs;
    }
  | {
      kind: 'inspect-query';
      query: string;
      operationName?: string;
      /** Response-key field path from the query root. */
      path: Array<{ field: string }>;
      /** OR-ed recursive partial matches applied before result materialization. */
      variableFilters?: QueryVariableFilter[];
    }
  | {
      kind: 'inspect-query-variants';
      query: string;
      operationName?: string;
      /** Response-key field path from the query root. */
      path: Array<{ field: string }>;
    }
  | { kind: 'teardown'; opId: string }
  /** External invalidation (e.g. websocket push): evict + report ops. */
  | { kind: 'invalidate'; keys: string[] }
  /** Apply explicit server-provided cache-deletion effects. */
  | { kind: 'delete-records'; keys: string[] }
  | { kind: 'clear' }
);

/** Stable machine-readable cache RPC rejection codes. */
export type CacheResponseErrorCode =
  | 'owner-epoch-lost'
  | 'owner-lock-unavailable'
  | 'owner-handoff-blocked'
  | 'admitted-enqueue-uncertain';

/** Old-owner work was rejected after fenced engine loss and was not replayed. */
export const OWNER_EPOCH_LOST_ERROR_CODE: CacheResponseErrorCode =
  'owner-epoch-lost';

/**
 * Another context holds the database, so this page's cache stays off until
 * reload: typically another deployed build keeps its owner lock, or a closing
 * tab's worker still has its files open. The request never reached an engine.
 */
export const OWNER_LOCK_UNAVAILABLE_ERROR_CODE: CacheResponseErrorCode =
  'owner-lock-unavailable';

/**
 * A read-only request was refused because the database was moving between
 * owners and the foreground wait ran out. Storage is untouched and the engine
 * keeps running, so the request can be retried once an owner is ready.
 */
export const OWNER_HANDOFF_BLOCKED_ERROR_CODE: CacheResponseErrorCode =
  'owner-handoff-blocked';

/** An admitted enqueue lost its reply and may already be durably queued. */
export const ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE: CacheResponseErrorCode =
  'admitted-enqueue-uncertain';

export type CacheResponse =
  | { id: number; ok: true; result: unknown }
  | {
      id: number;
      ok: false;
      error: string;
      errorCode?: CacheResponseErrorCode;
    };

/**
 * Pushed (not request/response) messages from worker to its client(s):
 * operations whose underlying records changed. The host filters by its own
 * clientId prefix and re-executes.
 */
export type CachePush =
  | {
      kind: 'ops-affected';
      opIds: string[];
      /** Changed entity keys, for diagnostics/advanced consumers. */
      keys: string[];
      fieldChanges?: RecordFieldChange[];
    }
  | ({
      kind: 'cache-changed';
      revision: CacheRevision;
      reset?: boolean;
    } & CacheChangeHints)
  | ({
      kind: 'cache-hydrated';
      revision: CacheRevision;
    } & CacheChangeHints)
  | { kind: 'mutation-settled'; settlement: MutationSettlement };

export type WorkerMessage = CacheResponse | CachePush;

type UnknownWireRecord = Record<string, unknown>;

const isWireRecord = (value: unknown): value is UnknownWireRecord =>
  typeof value === 'object' && value !== null && !Array.isArray(value);

const hasOnlyWireKeys = (
  value: UnknownWireRecord,
  keys: readonly string[]
): boolean => Object.keys(value).every((key) => keys.includes(key));

const isWireStringArray = (value: unknown): value is string[] =>
  Array.isArray(value) && value.every((item) => typeof item === 'string');

/** Strictly validates a machine-readable cache response error code. */
export const isCacheResponseErrorCode = (
  value: unknown
): value is CacheResponseErrorCode =>
  value === OWNER_EPOCH_LOST_ERROR_CODE ||
  value === OWNER_LOCK_UNAVAILABLE_ERROR_CODE ||
  value === OWNER_HANDOFF_BLOCKED_ERROR_CODE ||
  value === ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE;

/** Identifies a coordinator-fenced rejection from a lost owner epoch. */
export const isOwnerEpochLostError = (
  value: unknown
): value is Error & { errorCode: 'owner-epoch-lost' } =>
  value instanceof Error &&
  'errorCode' in value &&
  value.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;

/** Identifies a request refused because another context holds the database. */
export const isOwnerLockUnavailableError = (
  value: unknown
): value is Error & { errorCode: 'owner-lock-unavailable' } =>
  value instanceof Error &&
  'errorCode' in value &&
  value.errorCode === OWNER_LOCK_UNAVAILABLE_ERROR_CODE;

/** Identifies a read refused while the database moved between owners. */
export const isOwnerHandoffBlockedError = (
  value: unknown
): value is Error & { errorCode: 'owner-handoff-blocked' } =>
  value instanceof Error &&
  'errorCode' in value &&
  value.errorCode === OWNER_HANDOFF_BLOCKED_ERROR_CODE;

/** Identifies an admitted enqueue whose durable outcome is unknown. */
export const isAdmittedEnqueueUncertainError = (
  value: unknown
): value is Error & { errorCode: 'admitted-enqueue-uncertain' } =>
  value instanceof Error &&
  'errorCode' in value &&
  value.errorCode === ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE;

/** Strictly validates a cache response received across a host boundary. */
export function isCacheResponse(value: unknown): value is CacheResponse {
  if (
    !isWireRecord(value) ||
    !Number.isSafeInteger(value.id) ||
    (value.id as number) < 0
  ) {
    return false;
  }
  if (value.ok === true) {
    return (
      hasOnlyWireKeys(value, ['id', 'ok', 'result']) &&
      Object.hasOwn(value, 'result')
    );
  }
  return (
    value.ok === false &&
    hasOnlyWireKeys(value, ['id', 'ok', 'error', 'errorCode']) &&
    typeof value.error === 'string' &&
    (value.errorCode === undefined || isCacheResponseErrorCode(value.errorCode))
  );
}

/** Validates patches before they can be applied to live query objects. */
export function isRecordFieldChanges(
  value: unknown
): value is RecordFieldChange[] {
  return (
    Array.isArray(value) &&
    value.every((change) => {
      if (!isWireRecord(change) || typeof change.key !== 'string') return false;
      if (change.kind === 'invalidate')
        return hasOnlyWireKeys(change, ['kind', 'key']);
      return (
        change.kind === 'fields' &&
        hasOnlyWireKeys(change, ['kind', 'key', 'fields']) &&
        isWireRecord(change.fields) &&
        Object.values(change.fields).every(
          (field) =>
            field === null ||
            typeof field === 'string' ||
            typeof field === 'boolean' ||
            (typeof field === 'number' && Number.isFinite(field))
        )
      );
    })
  );
}

/** Strictly validates a pushed cache notification. */
export function isCachePush(value: unknown): value is CachePush {
  if (!isWireRecord(value)) return false;
  switch (value.kind) {
    case 'ops-affected':
      return (
        hasOnlyWireKeys(value, ['kind', 'opIds', 'keys', 'fieldChanges']) &&
        isWireStringArray(value.opIds) &&
        isWireStringArray(value.keys) &&
        (value.fieldChanges === undefined ||
          isRecordFieldChanges(value.fieldChanges))
      );
    case 'cache-changed':
      return (
        hasOnlyWireKeys(value, [
          'kind',
          'revision',
          'reset',
          'searchChangedBuckets',
          'unchangedViews',
        ]) &&
        isCacheRevision(value.revision) &&
        (value.reset === undefined || typeof value.reset === 'boolean') &&
        (value.unchangedViews === undefined ||
          isWireStringArray(value.unchangedViews)) &&
        (value.searchChangedBuckets === undefined ||
          isWireStringArray(value.searchChangedBuckets))
      );
    case 'cache-hydrated':
      return (
        hasOnlyWireKeys(value, [
          'kind',
          'revision',
          'searchChangedBuckets',
          'unchangedViews',
        ]) &&
        isCacheRevision(value.revision) &&
        (value.unchangedViews === undefined ||
          isWireStringArray(value.unchangedViews)) &&
        (value.searchChangedBuckets === undefined ||
          isWireStringArray(value.searchChangedBuckets))
      );
    case 'mutation-settled': {
      const settlement = value.settlement;
      if (
        !hasOnlyWireKeys(value, ['kind', 'settlement']) ||
        !isWireRecord(settlement) ||
        typeof settlement.transactionId !== 'string' ||
        (settlement.mutationUuid !== undefined &&
          typeof settlement.mutationUuid !== 'string')
      ) {
        return false;
      }
      if (settlement.status === 'committed') {
        return hasOnlyWireKeys(settlement, [
          'transactionId',
          'status',
          'mutationUuid',
        ]);
      }
      if (settlement.status === 'superseded') {
        return (
          hasOnlyWireKeys(settlement, [
            'transactionId',
            'mutationUuid',
            'status',
            'replacementTransactionId',
          ]) && typeof settlement.replacementTransactionId === 'string'
        );
      }
      return (
        settlement.status === 'permanently-failed' &&
        hasOnlyWireKeys(settlement, [
          'transactionId',
          'mutationUuid',
          'status',
          'error',
          'errorCode',
        ]) &&
        typeof settlement.error === 'string' &&
        (settlement.errorCode === undefined ||
          typeof settlement.errorCode === 'string')
      );
    }
    default:
      return false;
  }
}

/** Strictly validates any response or push delivered to a cache host. */
export const isWorkerMessage = (value: unknown): value is WorkerMessage =>
  isCacheResponse(value) || isCachePush(value);