Implement shared live fields and checked query hydration

Add native register acknowledgments and idempotent mutation replay, shared optimistic field controllers, overlapping custom setters, non-suspending hooks and explicit Suspense. Carry checked @live provenance through batched queries and hydrate shared browser fields with coverage leases. Update tracker/scaffolds/guides and verify compiler, PostgreSQL, browser and immutable workspace paths.

src/query/compile.ts

@@ -101,7 +101,7 @@ export async function compileQuery(
       if (node.name.value.startsWith("__")) fail("QUERY_UNSUPPORTED_FEATURE", "Introspection is not supported", node);
     },
     Directive(node) {
-      if (!["include", "skip"].includes(node.name.value))
+      if (!["include", "skip", "live"].includes(node.name.value))
         fail("QUERY_UNSUPPORTED_FEATURE", `Unsupported directive ${node.name.value}`, node);
     },
     InlineFragment(node) {
@@ -180,6 +180,15 @@ export async function compileQuery(
       Field(node) {
         const parent = info.getParentType();
         const contract = parent && generated.byName.get(parent.name);
+        if (node.directives?.some((directive) => directive.name.value === "live")) {
+          const member = contract?.members.find((entry) => entry.displayName === node.name.value);
+          if (!member || member.kind !== "value" || member.queryRead?.execution !== "native")
+            fail(
+              "QUERY_LIVE_UNSUPPORTED",
+              "@live requires a direct native-queryable value field, not RPC enrichment or a synthetic result",
+              node,
+            );
+        }
         if (!contract || node.name.value === "_qx") return;
         mark(contract.revisionId, node.name.value, "select", node);
         const member = contract.members.find((entry) => entry.displayName === node.name.value)!;
@@ -286,9 +295,12 @@ export async function compileQuery(
             field.type,
             selection.selectionSet,
             depth + 1,
-            conditional || !!selection.directives?.length,
+            conditional || !!selection.directives?.some((entry) => entry.name.value !== "live"),
           );
-          if ((conditional || selection.directives?.length) && fields[key]!.kind !== "optional")
+          if (
+            (conditional || selection.directives?.some((entry) => entry.name.value !== "live")) &&
+            fields[key]!.kind !== "optional"
+          )
             fields[key] = valueType.optional(fields[key]!);
           if (previous) fields[key] = mergeOutput(previous, fields[key]!);
         }
@@ -354,10 +366,12 @@ export async function compileQuery(
     }
   };
   const conditions = (directives: readonly DirectiveNode[] = []) =>
-    directives.map((directive) => ({
-      include: directive.name.value === "include",
-      value: argument(directive.arguments!.find((entry) => entry.name.value === "if")!.value),
-    }));
+    directives
+      .filter((directive) => directive.name.value !== "live")
+      .map((directive) => ({
+        include: directive.name.value === "include",
+        value: argument(directive.arguments!.find((entry) => entry.name.value === "if")!.value),
+      }));
   const selection = (
     set: SelectionSetNode,
     parent: import("graphql").GraphQLObjectType,
@@ -390,6 +404,13 @@ export async function compileQuery(
         {
           name: node.name.value,
           key: node.alias?.value ?? node.name.value,
+          ...(node.directives?.some((directive) => directive.name.value === "live")
+            ? {
+                liveSelectionId: createHash("sha256")
+                  .update(JSON.stringify([node.loc?.source.name, node.loc?.start, contract?.revisionId, member?.id]))
+                  .digest("hex"),
+              }
+            : {}),
           ...(member && contract ? { interfaceRevisionId: contract.revisionId, memberId: member.id } : {}),
           ...(member?.kind === "relationship" ? { targetInterfaceRevisionId: generated.target(member) } : {}),
           conditions: [...inherited, ...conditions(node.directives)],
@@ -405,6 +426,18 @@ export async function compileQuery(
   const normalized = print(document),
     schema = printSchema(generated.schema);
   const selections = selection(operations[0]!.selectionSet, generated.schema.getQueryType()!);
+  const checkPresentation = (entries: QuerySelection[]) => {
+    for (const key of new Set(entries.map((entry) => entry.key))) {
+      const siblings = entries.filter((entry) => entry.key === key);
+      if (siblings.some((entry) => entry.liveSelectionId) && siblings.some((entry) => !entry.liveSelectionId))
+        throw new QueryCompileError(
+          "QUERY_LIVE_CONFLICT",
+          `${key} mixes live and plain selections; use separate aliases`,
+        );
+      checkPresentation(siblings.flatMap((entry) => entry.selection));
+    }
+  };
+  checkPresentation(selections);
   const definitionDigest = createHash("sha256")
     .update(
       canonicalJson({

src/query/presentation.ts

@@ -0,0 +1,58 @@
+import type { InterfaceRevision, ValueType } from "../capability-model/types.js";
+import type { CheckedQuery, QuerySelection } from "./types.js";
+
+/** Browser presentation is separate from the portable query value contract. */
+export function queryPresentation(query: CheckedQuery, interfaces: readonly InterfaceRevision[]) {
+  const result: {
+    path: string[];
+    selectionId: string;
+    interfaceRevisionId: string;
+    getOperationId: string;
+    setOperationId?: string;
+    watchOperationId?: string;
+    inputKind: "value" | "fields";
+    valueType: ValueType;
+    conditions: (QuerySelection["conditions"][number] & { defaultValue?: boolean })[];
+  }[] = [];
+  const visit = (type: ValueType, selections: QuerySelection[], path: string[]) => {
+    if (type.kind === "optional") return visit(type.value, selections, path);
+    if (type.kind === "list") return visit(type.value, selections, [...path, "*"]);
+    if (type.kind !== "record") return;
+    for (const [name, field] of Object.entries(type.fields)) {
+      const matches = selections.filter((entry) => entry.key === name);
+      if (matches.some((entry) => entry.liveSelectionId) && matches.some((entry) => !entry.liveSelectionId))
+        throw new Error(`QUERY_LIVE_CONFLICT: ${[...path, name].join(".")} mixes live and plain selections`);
+      for (const entry of matches) {
+        if (entry.liveSelectionId) {
+          const iface = interfaces.find((iface) => iface.revisionId === entry.interfaceRevisionId)!;
+          const member = iface.members.find((member) => member.id === entry.memberId)!;
+          if (member.kind !== "value") throw new Error("QUERY_LIVE_UNSUPPORTED");
+          const get = member.operations.find((op) => op.displayName === "get")!;
+          const set = member.operations.find((op) => op.displayName === "set");
+          result.push({
+            path: [...path, name],
+            selectionId: entry.liveSelectionId,
+            interfaceRevisionId: iface.revisionId,
+            getOperationId: get.id,
+            setOperationId: set?.id,
+            watchOperationId: member.operations.find((op) => op.displayName === "watch-start")?.id,
+            inputKind: set?.inputType.kind === "record" ? "fields" : "value",
+            valueType: get.outputType,
+            conditions: entry.conditions.map((condition) => {
+              const fallback =
+                condition.value.kind === "variable" ? query.variableDefaults[condition.value.name] : undefined;
+              return {
+                ...condition,
+                ...(fallback?.kind === "literal" && typeof fallback.value === "boolean"
+                  ? { defaultValue: fallback.value }
+                  : {}),
+              };
+            }),
+          });
+        } else visit(field, entry.selection, [...path, name]);
+      }
+    }
+  };
+  visit(query.output, query.selection, []);
+  return result;
+}

src/query/schema.ts

@@ -10,6 +10,9 @@ import {
   GraphQLList,
   GraphQLNonNull,
   GraphQLSchema,
+  GraphQLDirective,
+  DirectiveLocation,
+  specifiedDirectives,
   type GraphQLOutputType,
   type GraphQLInputType,
   type GraphQLFieldConfigMap,
@@ -241,6 +244,7 @@ export function querySchema(
     return result;
   };
   const schema = new GraphQLSchema({
+    directives: [...specifiedDirectives, new GraphQLDirective({ name: "live", locations: [DirectiveLocation.FIELD] })],
     query: new GraphQLObjectType({
       name: "QxQuery",
       fields: { root: { type: new GraphQLNonNull(object(declaration.root)) } },

src/query/types.ts

@@ -98,6 +98,7 @@ export type QueryArgument =
   | { kind: "list"; values: QueryArgument[] }
   | { kind: "object"; fields: Record<string, QueryArgument> };
 export interface QuerySelection {
+  liveSelectionId?: string;
   name: string;
   key: string;
   interfaceRevisionId?: InterfaceRevisionId;