@kubun/mutation 0.17.0 → 0.18.0

package/lib/index.js

@@ -1,5 +1,8 @@
 export { HLC } from '@kubun/hlc';
-export { applyChangeMutation, applyMutation, applySetMutation, DEFAULT_MAX_DRIFT_MS, getTopLevelField } from './apply.js';
-export { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
-export { DocumentIDMismatchError, HLCDriftError, InvalidAccessPermissionsError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+export { isAccessSlotOnlyMutation } from './access-slot-only.js';
+export { applyChangeMutation, applyMutation, applySetMutation, applyTombstoneMutation, assembleDocumentData, classifySetOutcome, classifyTombstoneOutcome, DEFAULT_MAX_DRIFT_MS, DELETE_FETCH_KEY, getTopLevelField, providerGroupDigest, resolveModelPolicy, SET_FETCH_KEY, validateFetchTokenDrift, validateSetData, winnerStateDigestOf } from './apply.js';
+export { createChangeMutation, createRemoveMutation, createSetMutation, createTombstoneMutation } from './create.js';
+export { DocumentIDMismatchError, FetchTokenOrderError, HLCDriftError, IncompleteProviderGroupError, InvalidAccessPermissionsError, InvalidAccessRulePatchError, InvalidDefaultAccessPermissionsError, InvalidFetchTokenError, isPermanentApplyError, KubunMutationError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+export { selectHeldProviderWinner } from './observation-winner.js';
 export { convertPatchInput, createMutationOperations } from './operations.js';
+export { DELETED_STATE_DIGEST, stateDigest } from './state-digest.js';

package/lib/observation-winner.d.ts

@@ -0,0 +1,19 @@
+import type { SetDocumentMutation, TombstoneDocumentMutation } from '@kubun/protocol';
+import { type DocumentValidator, type ObservedProviderValue } from './apply.js';
+export type HeldProviderMutation = (SetDocumentMutation | TombstoneDocumentMutation) & {
+    sourceFetchHLC: string;
+};
+export type HeldProviderWinner = {
+    mutation: HeldProviderMutation;
+    token: string;
+    digest: string;
+    present: boolean;
+    group: Record<string, unknown>;
+};
+export type SelectHeldProviderWinnerParams = {
+    mutations: ReadonlyArray<HeldProviderMutation>;
+    observed: ObservedProviderValue;
+    fields: ReadonlyArray<string>;
+    validator: DocumentValidator;
+};
+export declare function selectHeldProviderWinner(params: SelectHeldProviderWinnerParams): HeldProviderWinner | null;

package/lib/observation-winner.js

@@ -0,0 +1,48 @@
+import { providerGroupDigest, validateSetData } from './apply.js';
+import { DELETED_STATE_DIGEST, stateDigest } from './state-digest.js';
+function candidate(mutation, fields, validator) {
+    const token = mutation.sourceFetchHLC;
+    if (mutation.typ === 'tombstone') {
+        return {
+            mutation,
+            token,
+            digest: DELETED_STATE_DIGEST,
+            present: false,
+            group: {}
+        };
+    }
+    const group = {};
+    const data = validateSetData(validator, mutation.data, mutation.sub);
+    for (const field of fields){
+        if (field in data) group[field] = data[field];
+    }
+    return {
+        mutation,
+        token,
+        digest: stateDigest({
+            state: 'live',
+            group
+        }),
+        present: true,
+        group
+    };
+}
+function comparesAfter(left, right) {
+    if (left.token !== right.token) return left.token > right.token;
+    if (left.present !== right.present) return !left.present;
+    return left.digest > right.digest;
+}
+export function selectHeldProviderWinner(params) {
+    const { mutations, observed, fields, validator } = params;
+    let base = null;
+    let qualifying = null;
+    for (const mutation of mutations){
+        const current = candidate(mutation, fields, validator);
+        if (base === null || comparesAfter(current, base)) base = current;
+        const matches = current.present === observed.present && (current.present ? providerGroupDigest(current.group) === observed.valueDigest : observed.valueDigest === null);
+        if (current.token >= observed.fetchHLC || matches) {
+            if (qualifying === null || comparesAfter(current, qualifying)) qualifying = current;
+        }
+    }
+    return qualifying ?? base;
+}

package/lib/operations.d.ts

@@ -1,6 +1,5 @@
-import type { PatchOperation } from '@kubun/graphql';
 import type { HLC } from '@kubun/hlc';
-import type { ChangeDocumentMutation, DocumentData, SetDocumentMutation } from '@kubun/protocol';
+import type { ChangeDocumentMutation, DocumentData, PatchOperation, SetDocumentMutation, TombstoneDocumentMutation } from '@kubun/protocol';
 import type { GetRandomValues } from '@sozai/runtime';
 export type CreateMutationOperationsParams<T> = {
     issuer: string;
@@ -10,6 +9,7 @@ export type CreateMutationOperationsParams<T> = {
     cap?: string | Array<string>;
     processSetMutation(mutation: SetDocumentMutation, transactionID?: string | null): Promise<T>;
     processChangeMutation(mutation: ChangeDocumentMutation, transactionID?: string | null): Promise<T>;
+    processTombstoneMutation?(mutation: TombstoneDocumentMutation, transactionID?: string | null): Promise<T>;
 };
 export type CreateDocumentParams = {
     modelID: string;
@@ -31,6 +31,7 @@ export type SetDocumentParams = {
      * Omitted means owner = the ops-level owner (or the signer when unset).
      */
     owner?: string;
+    sourceFetchHLC?: string;
 };
 export type UpdateDocumentParams = {
     docID: string;
@@ -41,11 +42,23 @@ export type RemoveDocumentParams = {
     docID: string;
     transactionID?: string | null;
 };
+export type TombstoneDocumentParams = {
+    modelID: string;
+    unique: Uint8Array;
+    sourceFetchHLC: string;
+    transactionID?: string | null;
+    /**
+     * Per-call document owner, overriding the ops-level owner for this write only.
+     * Omitted means owner = the ops-level owner (or the signer when unset).
+     */
+    owner?: string;
+};
 export type MutationOperations<T> = {
     createDocument(params: CreateDocumentParams): Promise<T>;
     setDocument(params: SetDocumentParams): Promise<T>;
     updateDocument(params: UpdateDocumentParams): Promise<T>;
     removeDocument(params: RemoveDocumentParams): Promise<T>;
+    tombstoneDocument(params: TombstoneDocumentParams): Promise<T>;
 };
 export declare function createMutationOperations<T>(params: CreateMutationOperationsParams<T>): MutationOperations<T>;
 export declare function convertPatchInput(patch: Array<Record<string, unknown>>): Array<PatchOperation>;

package/lib/operations.js

@@ -1,6 +1,6 @@
-import { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
+import { createChangeMutation, createRemoveMutation, createSetMutation, createTombstoneMutation } from './create.js';
 export function createMutationOperations(params) {
-    const { issuer, hlc, getRandomValues, owner, cap, processSetMutation, processChangeMutation } = params;
+    const { issuer, hlc, getRandomValues, owner, cap, processSetMutation, processChangeMutation, processTombstoneMutation } = params;
     return {
         async createDocument (params) {
             const { modelID, data, transactionID } = params;
@@ -17,7 +17,7 @@ export function createMutationOperations(params) {
             return await processSetMutation(mutation, transactionID);
         },
         async setDocument (params) {
-            const { modelID, unique, data, transactionID } = params;
+            const { modelID, unique, data, transactionID, sourceFetchHLC } = params;
             const mutation = await createSetMutation({
                 issuer,
                 hlc,
@@ -25,7 +25,8 @@ export function createMutationOperations(params) {
                 data,
                 unique,
                 owner: params.owner ?? owner,
-                cap
+                cap,
+                sourceFetchHLC
             });
             return await processSetMutation(mutation, transactionID);
         },
@@ -47,6 +48,22 @@ export function createMutationOperations(params) {
                 cap
             });
             return await processChangeMutation(mutation, transactionID);
+        },
+        async tombstoneDocument (params) {
+            if (processTombstoneMutation == null) {
+                throw new Error('tombstoneDocument requires processTombstoneMutation');
+            }
+            const { modelID, unique, sourceFetchHLC, transactionID } = params;
+            const mutation = await createTombstoneMutation({
+                issuer,
+                hlc,
+                modelID,
+                unique,
+                owner: params.owner ?? owner,
+                cap,
+                sourceFetchHLC
+            });
+            return await processTombstoneMutation(mutation, transactionID);
         }
     };
 }

package/lib/state-digest.d.ts

@@ -0,0 +1,16 @@
+/** The candidate's state, folded into one BLAKE3 digest with a liveness marker. */
+export type StateDigestInput = {
+    state: 'live';
+    group: Record<string, unknown>;
+} | {
+    state: 'deleted';
+};
+/**
+ * The candidate's state digest as a base64url (no padding) string. One
+ * definition serves the equal-token tiebreak, the `$setFetch`/`/fetch`
+ * registers, the watch watermarks, and the seam's candidate/winner digests.
+ * `group` excludes the fetch token, the digest itself, and every
+ * local-annotation field.
+ */
+export declare function stateDigest(input: StateDigestInput): string;
+export declare const DELETED_STATE_DIGEST: string;

package/lib/state-digest.js

@@ -0,0 +1,21 @@
+import { digestJSON } from '@kubun/id';
+import { toB64U } from '@sozai/codec';
+/**
+ * The candidate's state digest as a base64url (no padding) string. One
+ * definition serves the equal-token tiebreak, the `$setFetch`/`/fetch`
+ * registers, the watch watermarks, and the seam's candidate/winner digests.
+ * `group` excludes the fetch token, the digest itself, and every
+ * local-annotation field.
+ */ export function stateDigest(input) {
+    const canonical = input.state === 'live' ? {
+        state: 'live',
+        group: input.group
+    } : {
+        state: 'deleted'
+    };
+    const bytes = digestJSON(canonical);
+    return toB64U(bytes);
+}
+export const DELETED_STATE_DIGEST = stateDigest({
+    state: 'deleted'
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/mutation",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,16 +15,15 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/hlc": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@sozai/codec": "^0.4.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@sozai/codec": "^0.4.3",
     "@sozai/patch": "^0.1.3",
     "@sozai/runtime": "^0.1.0",
-    "@sozai/schema": "^0.1.2"
+    "@sozai/schema": "^0.1.4"
   },
   "devDependencies": {
-    "@kubun/graphql": "^0.17.0",
-    "@kubun/protocol": "^0.17.0"
+    "@kubun/protocol": "^0.18.0"
   },
   "publishConfig": {
     "access": "public"