@kubun/graphql 0.17.1 → 0.18.0

package/lib/context.d.ts

@@ -1,6 +1,7 @@
 import { DocumentID } from '@kubun/id';
 import type { AggregateHaving, AggregateSpec, AggregateValues, DocumentData, DocumentFilter, DocumentNode, DocumentOrderBy, GroupedAggregateOrderTerm, GroupedAggregateValue } from '@kubun/protocol';
-import type { SearchDocumentResult, SearchDocumentsParams, StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
+import type { SignedRecord } from '@kubun/records';
+import type { CatalogDefinition, CatalogLevel, CatalogRuleConflict, CatalogRuleResolutionInput, DocumentHold, DocumentScopeView, SearchDocumentResult, SearchDocumentsParams, StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
 import type { Tracer } from '@sozai/otel';
 import type { GraphQLResolveInfo } from 'graphql';
 import type { Connection, Edge } from './relay.js';
@@ -34,7 +35,10 @@ export type ReadContextDB = {
         filter?: DocumentFilter;
         orderBy?: DocumentOrderBy;
         owner?: string;
-        catalogID?: string;
+        catalogRef?: {
+            owner: string;
+            id: string;
+        };
         first?: number | null;
         last?: number | null;
         before?: string | null;
@@ -54,7 +58,10 @@ export type ReadContextDB = {
         modelIDs: Array<string>;
         filter?: DocumentFilter;
         owner?: string;
-        catalogID?: string;
+        catalogRef?: {
+            owner: string;
+            id: string;
+        };
         count: boolean;
         aggregates: Array<AggregateSpec>;
         readAccess?: ViewerReadAccess;
@@ -63,7 +70,10 @@ export type ReadContextDB = {
         modelIDs: Array<string>;
         filter?: DocumentFilter;
         owner?: string;
-        catalogID?: string;
+        catalogRef?: {
+            owner: string;
+            id: string;
+        };
         count: boolean;
         aggregates: Array<AggregateSpec>;
         groupBy: Array<{
@@ -86,7 +96,10 @@ export type AggregateScope = {
     modelIDs: Array<string>;
     filter?: DocumentFilter;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
 };
 /**
  * Connection value returned by {@link QueryContext.resolveConnection}. Extends
@@ -103,7 +116,10 @@ export type ScopedConnection = Connection<DocumentNode> & {
 export type ResolveAggregateParams = {
     filter?: DocumentFilter;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
     count: boolean;
     aggregates: Array<AggregateSpec>;
 };
@@ -116,7 +132,10 @@ export type ResolveAggregateParams = {
 export type ResolveGroupedAggregateParams = {
     filter?: DocumentFilter;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
     count: boolean;
     aggregates: Array<AggregateSpec>;
     groupBy: Array<{
@@ -158,6 +177,176 @@ export type SubscriptionContext = {
  * Query and subscription functions requiring server implementation
  */
 export type ReadOnlyContext = QueryContext & SubscriptionContext;
+export type CatalogRuleInput = Omit<CatalogRuleValue, 'id'> & {
+    id?: string;
+};
+export type CatalogRuleValue = {
+    id: string;
+    models?: Array<string>;
+    owners?: Array<string>;
+    maxAge?: string;
+    maxAhead?: string;
+    dateField?: string;
+};
+export type CatalogValue = {
+    id: string;
+    headVersionID: string;
+    upstream?: CatalogVersionRef;
+    name: string;
+    description?: string;
+    rules: Array<CatalogRuleValue>;
+    app?: string;
+};
+export type CatalogListing = {
+    id: string;
+    app: string | null;
+    name: string;
+    deletedAt: string | null;
+    catalog: CatalogValue | null;
+};
+export type CatalogVersionRef = {
+    catalogID: string;
+    versionID: string;
+};
+export type CatalogVersion = {
+    id: string;
+    catalogID: string;
+    parents: Array<CatalogVersionRef>;
+    catalog: CatalogValue;
+};
+export type CatalogVersionConnection = {
+    edges: Array<{
+        cursor: string;
+        node: CatalogVersion;
+    }>;
+    pageInfo: {
+        endCursor: string | null;
+        hasNextPage: boolean;
+    };
+};
+export type CatalogDraft = {
+    catalogID: string;
+    baseVersionID: string;
+    dirty: boolean;
+    updateAvailable: boolean;
+    catalog: CatalogValue;
+};
+export type CatalogUpdateInput = {
+    name?: string;
+    description?: string;
+    rules?: Array<CatalogRuleInput>;
+};
+export type FetchCatalogHeadVersionParams = {
+    catalogID: string;
+    versionID: string;
+    groupID: string;
+    peerDID: string;
+    /** Aborts once another member's copy decided the lookup. */
+    signal?: AbortSignal;
+};
+export type CatalogUpstreamUnavailableReason = 'NO_LIVE_OFFER' | 'UPSTREAM_DELETED' | 'BASE_MISSING' | 'VERSION_PENDING';
+export type CatalogUpstreamStatus = {
+    upstream: CatalogVersionRef | null;
+    latestVersionID: string | null;
+    updateAvailable: boolean;
+    unavailableReason: CatalogUpstreamUnavailableReason | null;
+};
+export type CatalogUpstreamLookup = {
+    status(id: string): Promise<CatalogUpstreamStatus>;
+    held(ref: CatalogVersionRef): Promise<SignedRecord | null>;
+    fetch(params: FetchCatalogHeadVersionParams): Promise<SignedRecord | null>;
+    eligible(catalogID: string): Promise<boolean>;
+};
+export type { CatalogRuleResolutionInput } from '@kubun/store-graph';
+export type CatalogPullPreview = {
+    baseVersionID: string;
+    localRevisionID: string;
+    upstreamVersionID: string;
+    merged: CatalogDefinition & {
+        id: string;
+    };
+    conflicts: Array<CatalogRuleConflict>;
+};
+export type CatalogPullResult = {
+    catalog: CatalogListing;
+    draft: CatalogDraft | null;
+    published: boolean;
+};
+export type ResolveCatalogPullParams = {
+    id: string;
+    baseVersionID: string;
+    localRevisionID: string;
+    upstreamVersionID: string;
+    resolutions: Array<CatalogRuleResolutionInput>;
+    publish: boolean;
+};
+export type CatalogDeviceStorage = {
+    catalogID: string;
+    level: CatalogLevel | null;
+    state: 'READY' | 'NEEDS_ROUTE';
+    matchingLocalDocuments: number;
+};
+export type CustodyStatus = 'NONE' | 'PENDING' | 'PARTIAL' | 'READY';
+export type CatalogCustody = {
+    catalogID: string;
+    custodians: Array<string>;
+    accepted: Array<string>;
+    /** Named custodians whose last word is that they take no custody. */
+    declined: Array<string>;
+    status: CustodyStatus;
+};
+export type CatalogContext = {
+    previewCatalogPull(id: string): Promise<CatalogPullPreview>;
+    resolveCatalogPull(params: ResolveCatalogPullParams): Promise<CatalogPullResult>;
+    cloneCatalog(id: string): Promise<CatalogListing>;
+    catalogUpstreamStatus(id: string): Promise<CatalogUpstreamStatus>;
+    createCatalog(input: {
+        name: string;
+        description?: string;
+        rules: Array<CatalogRuleInput>;
+        app?: string;
+    }): Promise<CatalogListing>;
+    updateCatalog(id: string, input: {
+        name?: string;
+        description?: string;
+        rules?: Array<CatalogRuleInput>;
+    }): Promise<CatalogListing>;
+    deleteCatalog(id: string): Promise<boolean>;
+    deduplicateAppCatalogs(app: string, name: string): Promise<CatalogListing | null>;
+    setCatalogDeviceLevel(id: string, level: CatalogLevel): Promise<CatalogDeviceStorage>;
+    catalogDeviceStorage(id: string): Promise<CatalogDeviceStorage>;
+    catalogCustody(id: string): Promise<CatalogCustody>;
+    /**
+     * Assign the catalog's custodians, superseding the current assignment. A custodian no longer
+     * named keeps its pins until a named custodian has accepted and answered held, so an empty list
+     * releases nothing: the old custodians keep their copies.
+     */
+    setCatalogCustodians(id: string, deviceDIDs: Array<string>): Promise<CatalogCustody>;
+    /** Whether this device accepts custody assignments; kept locally, over the engine default. */
+    setDeviceCustodyEligible(eligible: boolean): Promise<boolean>;
+    /**
+     * Write the next assignment without this device. Refused (`CUSTODY_ONLY_COPY`) while no other
+     * custodian accepted the current one, unless `force`. Pins go after another custodian's receipt,
+     * or at once with `force`, which deletes nothing.
+     */
+    leaveCatalogCustody(id: string, force: boolean): Promise<CatalogCustody>;
+    catalogs(includeDeleted: boolean): Promise<Array<CatalogListing>>;
+    catalogVersions(params: {
+        id: string;
+        first: number;
+        after?: string;
+    }): Promise<CatalogVersionConnection>;
+    catalogDraft(id: string): Promise<CatalogDraft | null>;
+    editCatalogDraft(id: string, input: CatalogUpdateInput): Promise<CatalogDraft>;
+    discardCatalogDraft(id: string): Promise<boolean>;
+    publishCatalogDraft(id: string, expectedHeadVersionID: string): Promise<CatalogListing>;
+    documentScope(id: string): Promise<DocumentScopeView>;
+    retainDocument(documentID: string, options: {
+        reason?: string;
+        expiresAt?: string;
+    }): Promise<DocumentHold>;
+    releaseDocumentHold(holdID: string): Promise<boolean>;
+};
 export type AccessChecker = (doc: DocumentNode, permissionType: 'read' | 'write') => Promise<boolean>;
 export type AccessWarning = {
     message: string;
@@ -174,7 +363,6 @@ export type ReadContextParams = {
     store: ReadContextDB;
     events?: DocumentEventEmitter;
     viewerDID: string;
-    catalogID?: string;
     accessChecker?: AccessChecker;
     viewerReadAccess?: ViewerReadAccess;
     warnings?: Array<AccessWarning>;
@@ -216,6 +404,13 @@ export type SetMutationParams = {
      * viewer) owns. Omitted means owner = signer (the ops-level owner).
      */
     owner?: string;
+    /**
+     * Fetch-order token for a merge-policy-aware SET, forwarded to the engine's
+     * outcome-bearing seam. A model that declares a `providerMergePolicy` rejects
+     * a tokenless write; ordinary models ignore it. Optional, so non-connector
+     * callers stay source-compatible.
+     */
+    sourceFetchHLC?: string;
 };
 export type UpdateMutationParams = {
     input: UpdateMutationInput;
@@ -249,6 +444,19 @@ export type SetDocumentAccessOverrideParams = {
 export type MutationContext = {
     executeCreateMutation(params: CreateMutationParams): Promise<DocumentNode>;
     executeSetMutation(params: SetMutationParams): Promise<DocumentNode>;
+    /**
+     * Outcome-bearing SET, present only on the engine's signing context. The
+     * client and service graph contexts do not implement it, so a consumer that
+     * needs the merge outcome asserts presence with a runtime null check and
+     * fails closed (throws) when it is absent, rather than mis-committing through
+     * the plain SET seam. `document` is null when a gate dropped the projection.
+     */
+    executeSetMutationWithOutcome?(params: SetMutationParams): Promise<{
+        document: DocumentNode | null;
+        outcome?: 'applied' | 'dominated' | 'nonconforming';
+        candidateDigest?: string;
+        winnerDigest?: string;
+    }>;
     executeUpdateMutation(params: UpdateMutationParams): Promise<DocumentNode>;
     executeRemoveMutation(params: RemoveMutationParams): Promise<void>;
     executeSetModelAccessDefaults(params: SetModelAccessDefaultsParams): Promise<ModelAccessDefaults>;
@@ -283,4 +491,6 @@ export type MutationContext = {
  */
 export interface PluginContextMap {
 }
-export type Context = ReadOnlyContext & MutationContext & Partial<PluginContextMap>;
+export type Context = ReadOnlyContext & MutationContext & {
+    catalog?: CatalogContext;
+} & Partial<PluginContextMap>;

package/lib/context.js

@@ -1,4 +1,4 @@
-import { DocumentID } from '@kubun/id';
+import { CatalogID, DocumentID } from '@kubun/id';
 import { getKubunLogger } from '@kubun/logger';
 import { KubunAttributeKeys, KubunSpanNames } from '@kubun/protocol';
 import { defer } from '@sozai/async';
@@ -243,8 +243,9 @@ export function createReadContext(params) {
                 modelIDs,
                 filter: args.filter,
                 owner: args.owner,
-                catalogID: params.catalogID
+                catalogRef: args.catalogID == null ? undefined : CatalogID.fromString(args.catalogID).toRecordKey()
             };
+            const catalogRef = aggregateScope.catalogRef;
             const result = await traced(KubunSpanNames.DATA_QUERY, {
                 [KubunAttributeKeys.MODEL_ID]: modelIDs.join(',')
             }, async ()=>{
@@ -253,7 +254,8 @@ export function createReadContext(params) {
                     const searchResults = await store.searchDocuments({
                         query: args.search,
                         modelIDs,
-                        first: 200
+                        first: 200,
+                        catalogRef
                     });
                     if (searchResults.length === 0) {
                         if (params.complexity != null) {
@@ -314,7 +316,7 @@ export function createReadContext(params) {
                     const { entries, hasMore } = await store.queryDocuments({
                         ...args,
                         modelIDs,
-                        catalogID: params.catalogID
+                        catalogRef
                     });
                     if (params.complexity != null) {
                         params.complexity.resolverCount++;
@@ -357,7 +359,7 @@ export function createReadContext(params) {
                         const { entries, hasMore } = await store.queryDocuments({
                             ...args,
                             modelIDs,
-                            catalogID: params.catalogID,
+                            catalogRef,
                             first: UNBOUNDED_SCAN_BATCH_SIZE,
                             after: cursor
                         });
@@ -399,7 +401,7 @@ export function createReadContext(params) {
                         const { entries, hasMore } = await store.queryDocuments({
                             ...args,
                             modelIDs,
-                            catalogID: params.catalogID,
+                            catalogRef,
                             first: fetchSize,
                             after: cursor
                         });
@@ -430,7 +432,7 @@ export function createReadContext(params) {
                         const { entries, hasMore } = await store.queryDocuments({
                             ...args,
                             modelIDs,
-                            catalogID: params.catalogID,
+                            catalogRef,
                             last: fetchSize,
                             before: cursor
                         });
@@ -539,7 +541,7 @@ export function createReadContext(params) {
                     modelIDs,
                     filter: aggregateParams.filter,
                     owner: aggregateParams.owner,
-                    catalogID: aggregateParams.catalogID ?? params.catalogID,
+                    catalogRef: aggregateParams.catalogRef,
                     count: aggregateParams.count,
                     aggregates: aggregateParams.aggregates,
                     readAccess: viewerReadAccess
@@ -565,7 +567,7 @@ export function createReadContext(params) {
                     modelIDs,
                     filter: groupedParams.filter,
                     owner: groupedParams.owner,
-                    catalogID: groupedParams.catalogID ?? params.catalogID,
+                    catalogRef: groupedParams.catalogRef,
                     count: groupedParams.count,
                     aggregates: groupedParams.aggregates,
                     groupBy: groupedParams.groupBy,

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export type { AccessWarning, AggregateScope, ComplexityStats, Context, CreateMutationParams, DocumentEventEmitter, DocumentSavedEvent, MutationContext, PluginContextMap, QueryContext, ReadContextDB, ReadContextParams, ReadOnlyContext, RemoveMutationParams, ScopedConnection, SetDocumentAccessOverrideParams, SetModelAccessDefaultsParams, SetMutationParams, SubscriptionContext, UpdateMutationParams, } from './context.js';
+export type { AccessWarning, AggregateScope, CatalogContext, CatalogCustody, CatalogDeviceStorage, CatalogDraft, CatalogListing, CatalogPullPreview, CatalogPullResult, CatalogRuleInput, CatalogRuleResolutionInput, CatalogRuleValue, CatalogUpdateInput, CatalogUpstreamLookup, CatalogUpstreamStatus, CatalogUpstreamUnavailableReason, CatalogValue, CatalogVersion, CatalogVersionConnection, CatalogVersionRef, ComplexityStats, Context, CreateMutationParams, CustodyStatus, DocumentEventEmitter, DocumentSavedEvent, FetchCatalogHeadVersionParams, MutationContext, PluginContextMap, QueryContext, ReadContextDB, ReadContextParams, ReadOnlyContext, RemoveMutationParams, ResolveCatalogPullParams, ScopedConnection, SetDocumentAccessOverrideParams, SetModelAccessDefaultsParams, SetMutationParams, SubscriptionContext, UpdateMutationParams, } from './context.js';
 export { createReadContext } from './context.js';
 export { GraphQLAttachmentID, GraphQLCredentialEntryID, GraphQLDocID, } from './identifiers.js';
 export type { ExtensionResolvers, SchemaBuilderParams, SharedDefinitions, } from './schema.js';

package/lib/schema.d.ts

@@ -94,6 +94,7 @@ export declare class SchemaBuilder {
     _relationsTo: Record<string, RelationFields>;
     _extensionSDL: string | undefined;
     _extensionResolvers: ExtensionResolvers | undefined;
+    _skippedTypeExtensions: Set<string>;
     _stubExtensionResolvers: boolean;
     _pluginNodeResolvers: Record<string, {
         resolve: (localID: string, ctx: Context) => Promise<unknown> | unknown;