import type { RuntimeIdentityRegistry } from "./query-keys.ts";

export type CacheScopeSnapshot = Readonly<{
  generation: number;
  fingerprint: string;
  identities: RuntimeIdentityRegistry;
  /** Aborted synchronously when this generation is fenced or disposed. */
  signal: AbortSignal;
  isCurrent(): boolean;
}>;

/**
 * §10.5. Client scope authority lifecycle.
 *
 * `FENCED` is published synchronously so no subscriber can render a value that
 * belonged to the previous identity. `READY` arrives only after the exact reset
 * sequence in §10.6 has completed.
 */
export type ClientScopeLifecycleEvent =
  | Readonly<{ kind: "FENCED"; previousGeneration: number }>
  | Readonly<{ kind: "READY"; snapshot: CacheScopeSnapshot }>
  | Readonly<{ kind: "FAILED"; generation: number }>
  | Readonly<{ kind: "DISPOSED" }>;

/** UI reads `FENCED` as the `scope-transition` state, never as stale data. */
export type ClientScopePhase = "READY" | "FENCED" | "FAILED" | "DISPOSED";

export type ServerStateScopeRuntime = Readonly<{
  getSnapshot(): CacheScopeSnapshot;
  getPhase(): ClientScopePhase;
  subscribe(listener: () => void): () => void;
  subscribeLifecycle(
    listener: (event: ClientScopeLifecycleEvent) => void,
  ): () => void;
  dispose(): void;
}>;