feat: 기능 추가 과정중

src/contracts/query-invalidation.ts

@@ -0,0 +1,45 @@
+import { isCacheInvalidationTopic } from "./cache-invalidation.ts";
+
+declare const queryInvalidationTopicBrand: unique symbol;
+
+/**
+ * Opaque registry-issued invalidation identity. The brand prevents feature
+ * code from accidentally passing a concrete query-key string to the mutation
+ * bridge.
+ */
+export type QueryInvalidationTopic = string &
+  Readonly<{ [queryInvalidationTopicBrand]: true }>;
+
+export function defineQueryInvalidationTopic(
+  value: string,
+): QueryInvalidationTopic {
+  if (!isCacheInvalidationTopic(value)) {
+    throw new TypeError("Query invalidation topic is invalid.");
+  }
+  return value as QueryInvalidationTopic;
+}
+
+export type QueryMutationLease = Readonly<{
+  /**
+   * Releases one local mutation fence. Remote hints coalesced while the fence
+   * was held are applied once after the final lease for each topic is released.
+   */
+  release(): Promise<void>;
+}>;
+
+/**
+ * Presentation-side facade for server-state invalidation.
+ *
+ * The caller knows only registry-issued topics. Query keys, BroadcastChannel
+ * envelopes and browser transports stay inside the query infrastructure.
+ */
+export interface QueryInvalidationCoordinator {
+  invalidate(topics: readonly QueryInvalidationTopic[]): Promise<void>;
+  beginMutation(topics: readonly QueryInvalidationTopic[]): QueryMutationLease;
+  /**
+   * Local verified lifecycle only. A remote invalidation hint is never allowed
+   * to clear the complete cache.
+   */
+  resetLocal(): Promise<void>;
+  dispose(): void;
+}