@kubun/graphql 0.17.1 → 0.18.0

package/lib/schema.js

@@ -1,7 +1,7 @@
-import { AttachmentID, DocumentID, DocumentModelID, decodeID, PluginNodeID } from '@kubun/id';
+import { AttachmentID, CatalogID, DocumentID, DocumentModelID, decodeID, PluginNodeID } from '@kubun/id';
 import { REFERENCE_PREFIX } from '@kubun/protocol';
 import { pascalCase } from 'change-case';
-import { extendSchema, GraphQLBoolean, GraphQLEnumType, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, isEnumType, isListType, isNonNullType, isObjectType, isScalarType, Kind, parse as parseGraphQL } from 'graphql';
+import { extendSchema, GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, isEnumType, isListType, isNonNullType, isObjectType, isScalarType, Kind, parse as parseGraphQL } from 'graphql';
 import { GraphQLDateTimeISO, GraphQLDID, GraphQLDuration, GraphQLEmailAddress, GraphQLJSON, GraphQLJSONObject } from 'graphql-scalars';
 import { GraphQLAttachmentID, GraphQLCredentialEntryID, GraphQLDocID } from './identifiers.js';
 import { connectionArgs, connectionDefinitions, mutationWithClientMutationId, nodeDefinitions } from './relay.js';
@@ -35,6 +35,8 @@ import { getUniqueDocValue, validateAccessIdentifiers } from './utils.js';
     // Object types: return empty object — sub-fields use their own stub resolvers
     return {};
 }
+// Marks an extension of a model type that applies only when the graph has it.
+const IF_TYPE_EXISTS = 'ifTypeExists';
 const STRING_FORMATS = {
     date: GraphQLString,
     time: GraphQLString,
@@ -356,6 +358,411 @@ const ModelAccessDefaults = new GraphQLObjectType({
             }
         })
 });
+const CatalogRuleInput = new GraphQLInputObjectType({
+    name: 'CatalogRuleInput',
+    fields: {
+        id: {
+            type: GraphQLID
+        },
+        models: {
+            type: toList(GraphQLString)
+        },
+        owners: {
+            type: toList(GraphQLString)
+        },
+        maxAge: {
+            type: GraphQLString
+        },
+        maxAhead: {
+            type: GraphQLString
+        },
+        dateField: {
+            type: GraphQLString
+        }
+    }
+});
+const CatalogRule = new GraphQLObjectType({
+    name: 'CatalogRule',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        models: {
+            type: toOuputList(GraphQLString)
+        },
+        owners: {
+            type: toOuputList(GraphQLString)
+        },
+        maxAge: {
+            type: GraphQLString
+        },
+        maxAhead: {
+            type: GraphQLString
+        },
+        dateField: {
+            type: GraphQLString
+        }
+    }
+});
+const CatalogVersionRef = new GraphQLObjectType({
+    name: 'CatalogVersionRef',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        versionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        }
+    }
+});
+const CatalogUpdateInput = new GraphQLInputObjectType({
+    name: 'CatalogUpdateInput',
+    fields: {
+        name: {
+            type: GraphQLString
+        },
+        description: {
+            type: GraphQLString
+        },
+        rules: {
+            type: toList(CatalogRuleInput)
+        }
+    }
+});
+const Catalog = new GraphQLObjectType({
+    name: 'Catalog',
+    fields: {
+        headVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        upstream: {
+            type: CatalogVersionRef
+        },
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        name: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        description: {
+            type: GraphQLString
+        },
+        rules: {
+            type: new GraphQLNonNull(toOuputList(CatalogRule))
+        },
+        app: {
+            type: GraphQLString
+        }
+    }
+});
+const CatalogListing = new GraphQLObjectType({
+    name: 'CatalogListing',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        app: {
+            type: GraphQLString
+        },
+        name: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        deletedAt: {
+            type: GraphQLString
+        },
+        catalog: {
+            type: Catalog
+        }
+    }
+});
+const CatalogVersion = new GraphQLObjectType({
+    name: 'CatalogVersion',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        parents: {
+            type: new GraphQLNonNull(toOuputList(CatalogVersionRef))
+        },
+        catalog: {
+            type: new GraphQLNonNull(Catalog)
+        }
+    }
+});
+const CatalogVersionEdge = new GraphQLObjectType({
+    name: 'CatalogVersionEdge',
+    fields: {
+        cursor: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        node: {
+            type: new GraphQLNonNull(CatalogVersion)
+        }
+    }
+});
+const CatalogVersionPageInfo = new GraphQLObjectType({
+    name: 'CatalogVersionPageInfo',
+    fields: {
+        endCursor: {
+            type: GraphQLString
+        },
+        hasNextPage: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        }
+    }
+});
+const CatalogVersionConnection = new GraphQLObjectType({
+    name: 'CatalogVersionConnection',
+    fields: {
+        edges: {
+            type: new GraphQLNonNull(toOuputList(CatalogVersionEdge))
+        },
+        pageInfo: {
+            type: new GraphQLNonNull(CatalogVersionPageInfo)
+        }
+    }
+});
+const CatalogDraft = new GraphQLObjectType({
+    name: 'CatalogDraft',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        baseVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        dirty: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        updateAvailable: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        catalog: {
+            type: new GraphQLNonNull(Catalog)
+        }
+    }
+});
+const CatalogDeviceLevel = new GraphQLEnumType({
+    name: 'CatalogDeviceLevel',
+    values: {
+        KNOWN: {},
+        OFFLINE: {},
+        SERVE_ONLY: {}
+    }
+});
+const CatalogLevelState = new GraphQLEnumType({
+    name: 'CatalogLevelState',
+    values: {
+        READY: {},
+        NEEDS_ROUTE: {}
+    }
+});
+const CatalogDeviceStorage = new GraphQLObjectType({
+    name: 'CatalogDeviceStorage',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        level: {
+            type: CatalogDeviceLevel
+        },
+        state: {
+            type: new GraphQLNonNull(CatalogLevelState)
+        },
+        matchingLocalDocuments: {
+            type: new GraphQLNonNull(GraphQLInt)
+        }
+    }
+});
+const CustodyStatus = new GraphQLEnumType({
+    name: 'CustodyStatus',
+    values: {
+        NONE: {},
+        PENDING: {},
+        PARTIAL: {},
+        READY: {}
+    }
+});
+const CatalogCustody = new GraphQLObjectType({
+    name: 'CatalogCustody',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        custodians: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        },
+        accepted: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        },
+        declined: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        },
+        status: {
+            type: new GraphQLNonNull(CustodyStatus)
+        }
+    }
+});
+const DocumentRetainHold = new GraphQLObjectType({
+    name: 'DocumentRetainHold',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        documentID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        reason: {
+            type: GraphQLString
+        },
+        expiresAt: {
+            type: GraphQLDateTimeISO,
+            resolve: (hold)=>hold.expiresAt == null ? null : new Date(hold.expiresAt)
+        }
+    }
+});
+const DocumentAvailability = new GraphQLEnumType({
+    name: 'DocumentAvailability',
+    values: {
+        LOCAL: {},
+        UNAVAILABLE: {}
+    }
+});
+const DocumentScope = new GraphQLObjectType({
+    name: 'DocumentScope',
+    fields: {
+        scope: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        availability: {
+            type: DocumentAvailability
+        },
+        retained: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        refs: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        }
+    }
+});
+const CatalogUpstreamUnavailableReason = new GraphQLEnumType({
+    name: 'CatalogUpstreamUnavailableReason',
+    values: {
+        NO_LIVE_OFFER: {},
+        UPSTREAM_DELETED: {},
+        BASE_MISSING: {},
+        VERSION_PENDING: {}
+    }
+});
+const CatalogUpstreamStatus = new GraphQLObjectType({
+    name: 'CatalogUpstreamStatus',
+    fields: {
+        upstream: {
+            type: CatalogVersionRef
+        },
+        latestVersionID: {
+            type: GraphQLID
+        },
+        updateAvailable: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        unavailableReason: {
+            type: CatalogUpstreamUnavailableReason
+        }
+    }
+});
+const CatalogRuleConflict = new GraphQLObjectType({
+    name: 'CatalogRuleConflict',
+    fields: {
+        ruleID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        base: {
+            type: CatalogRule
+        },
+        local: {
+            type: CatalogRule
+        },
+        upstream: {
+            type: CatalogRule
+        }
+    }
+});
+const CatalogPullPreview = new GraphQLObjectType({
+    name: 'CatalogPullPreview',
+    fields: {
+        baseVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        localRevisionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        upstreamVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        merged: {
+            type: new GraphQLNonNull(Catalog)
+        },
+        conflicts: {
+            type: new GraphQLNonNull(toOuputList(CatalogRuleConflict))
+        }
+    }
+});
+const CatalogPullResult = new GraphQLObjectType({
+    name: 'CatalogPullResult',
+    fields: {
+        catalog: {
+            type: new GraphQLNonNull(CatalogListing)
+        },
+        draft: {
+            type: CatalogDraft
+        },
+        published: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        }
+    }
+});
+const CatalogPullSide = new GraphQLEnumType({
+    name: 'CatalogPullSide',
+    values: {
+        LOCAL: {},
+        UPSTREAM: {}
+    }
+});
+const CatalogRuleResolutionInput = new GraphQLInputObjectType({
+    name: 'CatalogRuleResolutionInput',
+    fields: {
+        ruleID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        side: {
+            type: new GraphQLNonNull(CatalogPullSide)
+        }
+    }
+});
+function requireCatalog(ctx) {
+    if (ctx.catalog === undefined) throw new Error('Catalog context is unavailable');
+    return ctx.catalog;
+}
+async function catalogOperation(operation) {
+    try {
+        return await operation();
+    } catch (error) {
+        if (error instanceof Error && 'code' in error && (error.code === 'CATALOG_PULL_STALE' || error.code === 'CATALOG_RULES_EMPTY' || error.code === 'CATALOG_RULE_LIMIT_EXCEEDED' || error.code === 'INVALID_CATALOG_RULE' || error.code === 'CATALOG_DEVICE_LEVEL_DENIED' || error.code === 'CUSTODIAN_UNAVAILABLE' || error.code === 'CUSTODY_SIGNER_REQUIRED' || error.code === 'CUSTODY_ONLY_COPY' || error.code === 'DEVICE_OWNER_REQUIRED' || error.code === 'DOCUMENT_HOLD_DENIED' || error.code === 'DOCUMENT_HOLD_INVALID_EXPIRY' || error.code === 'DOCUMENT_NOT_HOLDABLE')) {
+            // biome-ignore lint/style/useErrorCause: GraphQLError retains the cause as originalError.
+            throw new GraphQLError(error.message, {
+                originalError: error,
+                extensions: {
+                    code: error.code
+                }
+            });
+        }
+        throw error;
+    }
+}
 export class SchemaBuilder {
     // Mapping of model or references IDs to their GraphQL object names
     _aliases;
@@ -388,6 +795,9 @@ export class SchemaBuilder {
     _relationsTo = {};
     _extensionSDL;
     _extensionResolvers;
+    // Types whose `@ifTypeExists` extension was left out: their `typeFields`
+    // are skipped rather than rejected.
+    _skippedTypeExtensions = new Set();
     _stubExtensionResolvers;
     _pluginNodeResolvers = {};
     _subscriptions = {};
@@ -535,7 +945,90 @@ export class SchemaBuilder {
         this._definitions = definitions;
         const queryFields = {
             nodes: definitions.nodesField,
-            ...definitions.queryFields
+            ...definitions.queryFields,
+            previewCatalogPull: {
+                type: new GraphQLNonNull(CatalogPullPreview),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).previewCatalogPull(args.id))
+            },
+            catalogVersions: {
+                type: new GraphQLNonNull(CatalogVersionConnection),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    first: {
+                        type: new GraphQLNonNull(GraphQLInt)
+                    },
+                    after: {
+                        type: GraphQLString
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogVersions({
+                        id: args.id,
+                        first: args.first,
+                        after: args.after ?? undefined
+                    })
+            },
+            catalogUpstreamStatus: {
+                type: new GraphQLNonNull(CatalogUpstreamStatus),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogUpstreamStatus(args.id)
+            },
+            catalogDraft: {
+                type: CatalogDraft,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogDraft(args.id)
+            },
+            catalogs: {
+                type: new GraphQLNonNull(toOuputList(CatalogListing)),
+                args: {
+                    includeDeleted: {
+                        type: GraphQLBoolean,
+                        defaultValue: false
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogs(args.includeDeleted === true)
+            },
+            catalogDeviceStorage: {
+                type: new GraphQLNonNull(CatalogDeviceStorage),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).catalogDeviceStorage(args.catalogID))
+            },
+            catalogCustody: {
+                type: new GraphQLNonNull(CatalogCustody),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).catalogCustody(args.catalogID))
+            },
+            documentScope: {
+                type: DocumentScope,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).documentScope(args.id)
+            }
         };
         for (const id of this._includedModelIDs){
             this._buildDocument(id);
@@ -553,6 +1046,9 @@ export class SchemaBuilder {
                     },
                     search: {
                         type: GraphQLString
+                    },
+                    catalogID: {
+                        type: GraphQLID
                     }
                 },
                 resolve: async (_, args, ctx)=>{
@@ -611,10 +1107,13 @@ export class SchemaBuilder {
                     },
                     after: {
                         type: GraphQLString
+                    },
+                    catalogID: {
+                        type: GraphQLID
                     }
                 },
                 resolve: async (_root, args, ctx)=>{
-                    const { query, models, first, after } = args;
+                    const { query, models, first, after, catalogID } = args;
                     if (query.trim() === '') {
                         throw new Error('Search query must not be empty');
                     }
@@ -632,7 +1131,8 @@ export class SchemaBuilder {
                         query,
                         modelIDs,
                         first: pageSize + 1,
-                        offset
+                        offset,
+                        catalogRef: catalogID == null ? undefined : CatalogID.fromString(catalogID).toRecordKey()
                     });
                     const hasNextPage = hits.length > pageSize;
                     const page = hasNextPage ? hits.slice(0, pageSize) : hits;
@@ -881,6 +1381,219 @@ export class SchemaBuilder {
                 }
             };
         }
+        if (this._includeMutations) {
+            this._mutations.editCatalogDraft = {
+                type: new GraphQLNonNull(CatalogDraft),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    input: {
+                        type: new GraphQLNonNull(CatalogUpdateInput)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).editCatalogDraft(args.id, args.input))
+            };
+            this._mutations.discardCatalogDraft = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).discardCatalogDraft(args.id))
+            };
+            this._mutations.publishCatalogDraft = {
+                type: new GraphQLNonNull(CatalogListing),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    expectedHeadVersionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).publishCatalogDraft(args.id, args.expectedHeadVersionID))
+            };
+            this._mutations.resolveCatalogPull = {
+                type: new GraphQLNonNull(CatalogPullResult),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    baseVersionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    localRevisionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    upstreamVersionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    resolutions: {
+                        type: new GraphQLNonNull(toList(CatalogRuleResolutionInput))
+                    },
+                    publish: {
+                        type: new GraphQLNonNull(GraphQLBoolean)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).resolveCatalogPull(args))
+            };
+            this._mutations.cloneCatalog = {
+                type: new GraphQLNonNull(CatalogListing),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).cloneCatalog(args.id))
+            };
+            this._mutations.createCatalog = {
+                type: Catalog,
+                args: {
+                    name: {
+                        type: new GraphQLNonNull(GraphQLString)
+                    },
+                    description: {
+                        type: GraphQLString
+                    },
+                    rules: {
+                        type: new GraphQLNonNull(toList(CatalogRuleInput))
+                    },
+                    app: {
+                        type: GraphQLString
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(async ()=>{
+                        const listing = await requireCatalog(ctx).createCatalog({
+                            name: args.name,
+                            description: args.description ?? undefined,
+                            rules: args.rules,
+                            app: args.app ?? undefined
+                        });
+                        return listing.catalog;
+                    })
+            };
+            this._mutations.updateCatalog = {
+                type: Catalog,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    name: {
+                        type: GraphQLString
+                    },
+                    description: {
+                        type: GraphQLString
+                    },
+                    rules: {
+                        type: toList(CatalogRuleInput)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(async ()=>{
+                        const listing = await requireCatalog(ctx).updateCatalog(args.id, {
+                            name: args.name ?? undefined,
+                            description: args.description ?? undefined,
+                            rules: args.rules ?? undefined
+                        });
+                        return listing.catalog;
+                    })
+            };
+            this._mutations.deleteCatalog = {
+                type: GraphQLBoolean,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).deleteCatalog(args.id)
+            };
+            this._mutations.deduplicateAppCatalogs = {
+                type: Catalog,
+                args: {
+                    app: {
+                        type: new GraphQLNonNull(GraphQLString)
+                    },
+                    name: {
+                        type: new GraphQLNonNull(GraphQLString)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>(await requireCatalog(ctx).deduplicateAppCatalogs(args.app, args.name))?.catalog ?? null
+            };
+            this._mutations.setCatalogDeviceLevel = {
+                type: new GraphQLNonNull(CatalogDeviceStorage),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    level: {
+                        type: new GraphQLNonNull(CatalogDeviceLevel)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).setCatalogDeviceLevel(args.catalogID, args.level))
+            };
+            this._mutations.setCatalogCustodians = {
+                type: new GraphQLNonNull(CatalogCustody),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    deviceDIDs: {
+                        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLString)))
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).setCatalogCustodians(args.catalogID, args.deviceDIDs))
+            };
+            this._mutations.setDeviceCustodyEligible = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                args: {
+                    eligible: {
+                        type: new GraphQLNonNull(GraphQLBoolean)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).setDeviceCustodyEligible(args.eligible))
+            };
+            this._mutations.leaveCatalogCustody = {
+                type: new GraphQLNonNull(CatalogCustody),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    force: {
+                        type: GraphQLBoolean,
+                        defaultValue: false
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).leaveCatalogCustody(args.catalogID, args.force === true))
+            };
+            this._mutations.retainDocument = {
+                type: new GraphQLNonNull(DocumentRetainHold),
+                args: {
+                    documentID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    reason: {
+                        type: GraphQLString
+                    },
+                    expiresAt: {
+                        type: GraphQLDateTimeISO
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).retainDocument(args.documentID, {
+                            reason: args.reason ?? undefined,
+                            expiresAt: args.expiresAt?.toISOString()
+                        }))
+            };
+            this._mutations.releaseDocumentHold = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                args: {
+                    holdID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).releaseDocumentHold(args.holdID))
+            };
+        }
         const config = {
             query: new GraphQLObjectType({
                 name: 'Query',
@@ -968,10 +1681,14 @@ export class SchemaBuilder {
         // Apply SDL extensions
         if (this._extensionSDL != null) {
             const typesBefore = new Set(Object.keys(schema.getTypeMap()));
-            schema = extendSchema(schema, parseGraphQL(this._extensionSDL));
+            const fieldsBefore = new Map();
+            for (const [typeName, type] of Object.entries(schema.getTypeMap())){
+                if (isObjectType(type)) fieldsBefore.set(typeName, new Set(Object.keys(type.getFields())));
+            }
+            schema = extendSchema(schema, this.#applicableExtensions(schema, this._extensionSDL));
             // Stub extension resolvers for client-side pre-execution
             if (this._stubExtensionResolvers) {
-                this.#stubExtensionFields(schema, typesBefore);
+                this.#stubExtensionFields(schema, typesBefore, fieldsBefore);
             }
         }
         // Attach resolvers to extended fields
@@ -980,6 +1697,35 @@ export class SchemaBuilder {
         }
         return schema;
     }
+    /**
+   * The extension SDL to apply. `extend type T @ifTypeExists { ... }` extends
+   * `T` only when the schema built from the models has it — a plugin can add
+   * fields to model types a graph may or may not include — and is otherwise
+   * left out, along with the `typeFields` given for `T`. The directive is a
+   * build instruction only and never reaches the schema.
+   */ #applicableExtensions(schema, sdl) {
+        const document = parseGraphQL(sdl);
+        const definitions = [];
+        for (const definition of document.definitions){
+            const conditional = definition.kind === Kind.OBJECT_TYPE_EXTENSION && definition.directives?.some((directive)=>directive.name.value === IF_TYPE_EXISTS);
+            if (!conditional) {
+                definitions.push(definition);
+                continue;
+            }
+            if (schema.getType(definition.name.value) == null) {
+                this._skippedTypeExtensions.add(definition.name.value);
+                continue;
+            }
+            definitions.push({
+                ...definition,
+                directives: definition.directives?.filter((directive)=>directive.name.value !== IF_TYPE_EXISTS)
+            });
+        }
+        return {
+            ...document,
+            definitions
+        };
+    }
     #attachExtensionResolvers(schema, resolvers) {
         const queryType = schema.getQueryType();
         if (queryType != null && resolvers.queryFields != null) {
@@ -1014,6 +1760,7 @@ export class SchemaBuilder {
         }
         if (resolvers.typeFields != null) {
             for (const [typeName, fieldResolvers] of Object.entries(resolvers.typeFields)){
+                if (this._skippedTypeExtensions.has(typeName)) continue;
                 const type = schema.getType(typeName);
                 if (type == null) {
                     throw new Error(`Extension resolver references type "${typeName}" which does not exist in the schema`);
@@ -1036,7 +1783,7 @@ export class SchemaBuilder {
             }
         }
     }
-    #stubExtensionFields(schema, typesBefore) {
+    #stubExtensionFields(schema, typesBefore, fieldsBefore) {
         // Stub root Query/Mutation fields added by extension SDL
         for (const rootType of [
             schema.getQueryType(),
@@ -1050,15 +1797,22 @@ export class SchemaBuilder {
                 }
             }
         }
-        // Stub fields on types added by extension SDL
+        // Stub fields on types added by extension SDL, and fields an extension
+        // added to an existing type
         for (const [typeName, type] of Object.entries(schema.getTypeMap())){
-            if (typesBefore.has(typeName)) continue;
             if (!isObjectType(type)) continue;
+            const existing = typesBefore.has(typeName) ? fieldsBefore.get(typeName) ?? null : null;
+            if (typesBefore.has(typeName) && existing == null) continue;
             const fields = type.getFields();
             for (const field of Object.values(fields)){
+                if (existing?.has(field.name) === true) continue;
                 if (field.resolve == null) {
                     const fieldType = field.type;
-                    field.resolve = (source)=>source[field.name] ?? createDefaultValue(fieldType);
+                    // A nullable field added to an existing type (a model's) stubs as
+                    // null: a made-up value, such as an enum's first member, would read
+                    // as a real one.
+                    const stubsNull = existing != null && !isNonNullType(fieldType);
+                    field.resolve = (source)=>source[field.name] ?? (stubsNull ? null : createDefaultValue(fieldType));
                 }
             }
         }
@@ -1162,12 +1916,15 @@ export class SchemaBuilder {
         }, (node)=>{
             if (typeof node === 'string') return 'AccountNode';
             if (node instanceof AttachmentID) return 'AttachmentNode';
-            if (node != null && typeof node === 'object' && 'model' in node) {
-                return this._aliases[node.model];
-            }
+            // An explicit type (set on a plugin node above) wins over the document
+            // heuristic, so a plugin node whose source has a `model` key is not
+            // taken for a document.
             if (node != null && typeof node === 'object' && '__typename' in node) {
                 return node.__typename;
             }
+            if (node != null && typeof node === 'object' && 'model' in node) {
+                return this._aliases[node.model];
+            }
             throw new Error('Unknown node type');
         });
         const accountObject = new GraphQLObjectType({
@@ -1351,7 +2108,7 @@ export class SchemaBuilder {
                             return await ctx.resolveAggregate(scope.modelIDs, {
                                 filter: scope.filter,
                                 owner: scope.owner,
-                                catalogID: scope.catalogID,
+                                catalogRef: scope.catalogRef,
                                 count,
                                 aggregates
                             });
@@ -1393,7 +2150,7 @@ export class SchemaBuilder {
                             return await ctx.resolveGroupedAggregate(scope.modelIDs, {
                                 filter: scope.filter,
                                 owner: scope.owner,
-                                catalogID: scope.catalogID,
+                                catalogRef: scope.catalogRef,
                                 count,
                                 aggregates,
                                 groupBy,