Implement independent presentation readiness boundaries

src/query/compile.ts

@@ -4,6 +4,8 @@ import {
   validate,
   specifiedRules,
   PossibleFragmentSpreadsRule,
+  NoUnusedVariablesRule,
+  GraphQLError,
   print,
   printSchema,
   visit,
@@ -201,10 +203,29 @@ export async function compileQuery(
       },
     }),
   );
+  const bindingVariables = new Set(
+    [...fragmentContracts.values()]
+      .filter((entry) => entry.mode === "reference")
+      .flatMap((entry) => Object.values(entry.variables)),
+  );
   const errors = validate(
     generated.schema,
     document,
-    specifiedRules.filter((rule) => rule !== PossibleFragmentSpreadsRule),
+    [
+      ...specifiedRules.filter((rule) => rule !== PossibleFragmentSpreadsRule && rule !== NoUnusedVariablesRule),
+      (context) => ({
+        OperationDefinition: {
+          leave(operation) {
+            const used = new Set(context.getRecursiveVariableUsages(operation).map(({ node }) => node.name.value));
+            for (const variable of operation.variableDefinitions ?? []) {
+              const name = variable.variable.name.value;
+              if (!used.has(name) && !bindingVariables.has(name))
+                context.reportError(new GraphQLError(`Variable "$${name}" is never used.`, { nodes: variable }));
+            }
+          },
+        },
+      }),
+    ],
     { maxErrors: 20 },
   );
   if (errors.length) {
@@ -399,6 +420,7 @@ export async function compileQuery(
         for (const selection of set.selections) {
           if (++expandedFields > 10000) fail("QUERY_WORK_LIMIT", "Expanded query exceeds 10000 fields", selection);
           if (selection.kind === "FragmentSpread") {
+            if (fragmentContracts.get(selection.name.value)?.mode === "reference") continue;
             add(
               fragments.get(selection.name.value)!.selectionSet,
               conditional || !!selection.directives?.length,
@@ -530,7 +552,9 @@ export async function compileQuery(
                 },
               ]
             : []),
-          ...selection(fragments.get(node.name.value)!.selectionSet, parent, inheritedConditions),
+          ...(contract?.mode === "reference"
+            ? []
+            : selection(fragments.get(node.name.value)!.selectionSet, parent, inheritedConditions)),
         ];
       }
       if (node.kind !== "Field") return [];
@@ -610,9 +634,10 @@ export async function compileQuery(
   const definitionDigest = createHash("sha256")
     .update(
       canonicalJson({
-        semantics: 4,
+        semantics: 5,
         declaration,
         normalized,
+        fragmentContracts: Object.fromEntries(fragmentContracts),
         // Source provenance belongs to the checked installation. Identical public
         // contracts keep their query identity when retained in another repository.
         // Closed generic identity remains explicit in revisionId/application.

src/query/fragments.ts

@@ -11,6 +11,8 @@ export async function fragmentSources(
 ) {
   const markers = new Map<string, NonNullable<QuerySelection["fragmentSpread"]>>();
   for (const imported of declaration.importedFragments ?? []) {
+    if (imported.mode !== undefined && imported.mode !== "reference")
+      throw new QueryCompileError("FRAGMENT_IMPORT_MODE", "Unknown fragment import mode");
     if (!resolve)
       throw new QueryCompileError(
         "FRAGMENT_RESOLVER_REQUIRED",
@@ -57,7 +59,16 @@ export async function fragmentSources(
         node.name.value === exported.name ? exported.name : `${exported.name}__${node.name.value}`,
       ]),
     );
-    for (const fragment of fragments) {
+    // A reference import binds the checked export, rather than spreading its
+    // fields into this operation. Keep a nominal stub for GraphQL root checking;
+    // the independently checked export supplies the actual projection contract.
+    const referenced = parse("fragment Binding on Placeholder { _camino { ref } }")
+      .definitions[0] as FragmentDefinitionNode;
+    for (const sourceFragment of imported.mode === "reference"
+      ? fragments.filter((entry) => entry.name.value === exported.name)
+      : fragments) {
+      const fragment =
+        imported.mode === "reference" ? { ...sourceFragment, selectionSet: referenced.selectionSet } : sourceFragment;
       definitions.push(
         visit(fragment, {
           FragmentDefinition(node) {
@@ -73,13 +84,16 @@ export async function fragmentSources(
       );
     }
     markers.set(exported.name, {
+      ...(imported.mode ? { mode: imported.mode } : {}),
       package: imported.packageRevisionId,
       fragment: imported.fragmentId,
       digest: checked.definitionDigest,
       root: checked.declaration.root.interface,
       variables: imported.variables,
     });
-    for (const [name, contract] of Object.entries(checked.fragmentContracts ?? {})) {
+    for (const [name, contract] of Object.entries(
+      imported.mode === "reference" ? {} : (checked.fragmentContracts ?? {}),
+    )) {
       markers.set(privateNames.get(name) ?? name, {
         ...contract,
         variables: Object.fromEntries(

src/query/types.ts

@@ -38,6 +38,9 @@ export interface QueryDeclaration {
   /** Exported local projection; compilation also creates its direct admission. */
   fragment?: { name: string; operation?: string; admission?: boolean };
   importedFragments?: {
+    /** Bind an independently observed fragment without including its fields in
+     * this projection. Its acquisition is still an explicit replica source. */
+    mode?: "reference";
     packageRevisionId: string;
     packageAlias?: string;
     fragmentId: string;
@@ -113,6 +116,7 @@ export type QueryArgument =
 export interface QuerySelection {
   /** A checked occurrence marker, not an output field or storage capability. */
   fragmentSpread?: {
+    mode?: "reference";
     package: string;
     fragment: string;
     digest: string;