@kubun/mutation 0.16.0 → 0.17.1

package/lib/apply.d.ts

@@ -1,10 +1,26 @@
 import { HLC } from '@kubun/hlc';
 import type { DocumentModelID } from '@kubun/id';
 import { DocumentID } from '@kubun/id';
-import type { ChangeDocumentMutation, DocumentData, DocumentModel, DocumentMutation, DocumentNode, SetDocumentMutation } from '@kubun/protocol';
+import type { ChangeDocumentMutation, DocumentData, DocumentModel, DocumentMutation, DocumentNode, SetDocumentMutation, TombstoneDocumentMutation } from '@kubun/protocol';
 import { type Validator } from '@sozai/schema';
 export type DocumentValidator = Validator<DocumentData>;
 export type ValidatorsRecord = Record<string, Promise<DocumentValidator>>;
+/**
+ * Reserved key holding a merge-policy model's winning-live fetch-order
+ * register for its provider group: `{ hlc, digest }`, the greatest
+ * `sourceFetchHLC` observed for a live candidate, paired with that
+ * candidate's state digest. The bare `hlc` also lands in `field_hlcs` under
+ * this same key (mirroring `SET_KEY`) for the total-order comparison;
+ * `field_values` carries the full cell so `winnerStateDigestOf` can read the
+ * digest without a second store round trip.
+ */
+export declare const SET_FETCH_KEY = "$setFetch";
+/**
+ * Reserved key holding a merge-policy model's winning-delete fetch-order
+ * register: `{ hlc }`, the greatest deleting `sourceFetchHLC` observed. Same
+ * `field_hlcs`/`field_values` split as `SET_FETCH_KEY`.
+ */
+export declare const DELETE_FETCH_KEY = "/fetch";
 /**
  * Post-state access gate evaluated AFTER the post-apply `DocumentNode` is
  * computed in memory but BEFORE any persist call. Returning `false` instructs
@@ -65,7 +81,126 @@ export declare function getDocumentValidator(ctx: MutationContext, id: string):
  * lands whenever it lands.
  */
 export declare const DEFAULT_MAX_DRIFT_MS = 3600000;
+export declare function validateFetchTokenDrift(token: string, maxDriftMS: number): void;
 export declare function getTopLevelField(path: string): string;
-export declare function applyChangeMutation(ctx: MutationContext, mutation: ChangeDocumentMutation): Promise<DocumentNode | null>;
-export declare function applySetMutation(ctx: MutationContext, mutation: SetDocumentMutation): Promise<DocumentNode | null>;
-export declare function applyMutation(ctx: MutationContext, mutation: DocumentMutation): Promise<DocumentNode | null>;
+/**
+ * A model's provider merge policy, or `null` for an ordinary model. Read
+ * straight from the store on every call (no cache) since it gates which
+ * branch a SET/tombstone apply takes. `requiredGroupFields` is the subset of
+ * `group` the model schema's own `required` array names — the fields a
+ * complete-group SET may never omit (an omitted OPTIONAL group field is
+ * legitimate: it clears that field's stored value on a winning SET instead).
+ */
+export declare function resolveModelPolicy(ctx: MutationContext, modelID: DocumentModelID | string): Promise<{
+    group: Array<string>;
+    requiredGroupFields: ReadonlySet<string>;
+} | null>;
+/**
+ * The winning side of a merge-policy document's fetch-order registers: its
+ * token, its state digest (the live `$setFetch` digest, or the constant
+ * `DELETED_STATE_DIGEST` when the delete side wins), and whether that side is
+ * live. Shared by `winnerStateDigestOf` (the digest-only public read) and the
+ * SET classifier/register-winner logic below, which also need the frontier's
+ * own token and liveness to compare a candidate against it.
+ */
+export type FetchFrontier = {
+    hlc: string;
+    digest: string;
+    alive: boolean;
+};
+/**
+ * Pure merge-policy liveness read: the winning side's state digest alone —
+ * the live `$setFetch` digest, or `DELETED_STATE_DIGEST` when the delete side
+ * wins, or `null` when neither register is present. This is what lets
+ * `@kubun/store-graph`'s `readWinnerStateDigest` reuse the comparison after
+ * its own single-column read instead of also threading `field_hlcs`.
+ */
+export declare function winnerStateDigestOf(fieldValues: Record<string, unknown>): string | null;
+/**
+ * The diagnostic outcome of applying a candidate against a merge-policy
+ * document's provider group. `applied` and `dominated` are pure functions of
+ * arrival order and state (never authorization); `nonconforming` flags an
+ * exact-token disagreement the total order still resolves deterministically.
+ */
+export type MergeOutcome = 'applied' | 'dominated' | 'nonconforming';
+/**
+ * The result of applying a mutation. `document` is the thin compat surface
+ * every caller reads. The remaining fields are present together only for a
+ * non-null application against a merge-policy provider group's SET or
+ * tombstone path: `outcome` is `classifySetOutcome`/`classifyTombstoneOutcome`'s
+ * diagnostic label, `candidateDigest` the incoming candidate's own state
+ * digest, `winnerDigest` the register winner's state digest after this apply,
+ * and `winnerChanged` whether that winner digest moved from before to after.
+ *
+ * `outcome` and `winnerChanged` are independent signals, not the same
+ * question asked twice. `outcome` classifies the candidate's standing
+ * against the total order: `applied` means the candidate is a valid member
+ * of the current frontier, which includes an idempotent re-projection of
+ * content the frontier already holds (an exact-token, equal-digest replay —
+ * `winnerChanged` is `false` there, since the register's digest never
+ * moved). `nonconforming` flags an exact-token disagreement in content; the
+ * total order still resolves it deterministically to one side or the other,
+ * so a `nonconforming` candidate can itself either win (`winnerChanged:
+ * true`, its digest becomes the new winner) or lose (`winnerChanged:
+ * false`) — the label alone does not say which. Whether the register's
+ * winning digest actually moved is answered by `winnerChanged` alone, never
+ * inferred from the `outcome` label. Outcome and digest equality are a
+ * third, separate independent axis: a `dominated` candidate can carry
+ * either an equal or unequal digest against the winner. An ordinary-model
+ * application, a CHANGE application, and a dropped (gate-denied or
+ * null-document) application carry none of the four — just `{ document }`.
+ */
+export type MutationApplyResult = {
+    document: DocumentNode | null;
+    outcome?: MergeOutcome;
+    candidateDigest?: string;
+    winnerDigest?: string;
+    winnerChanged?: boolean;
+};
+/**
+ * Fetch-token-first diagnostic classification of an incoming live SET
+ * candidate against the stored frontier (`F_hlc` = the frontier's own token,
+ * equal to `max(setFetchHLC, deleteFetchHLC)` by construction — whichever
+ * register wins carries the greater of the two). Discriminates on the
+ * candidate's token alone; state/digest is inspected only at an exact token
+ * tie, so this is exclusive and total: a below-frontier candidate is never
+ * simultaneously `dominated` (hash irrelevant beneath the frontier) and
+ * `nonconforming` (hash only inspected at an exact tie).
+ *
+ * This is the diagnostic label only — separate from which side the register
+ * actually keeps (`setWinsFrontier` below). At an exact tie with unequal
+ * digests the register still picks the lexically greater one deterministically,
+ * even though the label stays `nonconforming` for both directions: the label
+ * flags the disagreement, it does not report which side won it.
+ */
+export declare function classifySetOutcome(token: string, candidateDigest: string, frontier: FetchFrontier | null): MergeOutcome;
+/**
+ * Fetch-token-first diagnostic classification of an incoming tombstone
+ * candidate against the stored frontier, mirroring `classifySetOutcome`. At
+ * an exact token tie the register always keeps the delete (fail-safe), so a
+ * tie against an already-deleted frontier is `applied` (idempotent
+ * re-tombstoning) while a tie against a live frontier is `nonconforming` —
+ * the label flags the disagreement even though the register still resolves
+ * it deterministically to the delete.
+ */
+export declare function classifyTombstoneOutcome(token: string, frontier: FetchFrontier | null): MergeOutcome;
+export declare function applyChangeMutation(ctx: MutationContext, mutation: ChangeDocumentMutation): Promise<MutationApplyResult>;
+export declare function applySetMutation(ctx: MutationContext, mutation: SetDocumentMutation): Promise<MutationApplyResult>;
+/**
+ * A fetch-token-carrying deletion on a merge-policy document's `/fetch`
+ * liveness register. Unlike `applyChangeMutation`'s delete branch, a
+ * tombstone may arrive before the document exists at all — it carries the
+ * full SET-equivalent creation-and-authorization surface (`aud`/`unq`) so a
+ * first-seen tombstone can establish a `data: null` row exactly as a SET
+ * creates state from `owner`+`unq`. Ordering is governed by the same total
+ * key as the set side (`deleteWinsFrontier`), so sets and deletes commute
+ * regardless of arrival order.
+ *
+ * A tombstone is a merge-policy-only concept — an ordinary model deletes via
+ * the `/`→null CHANGE path, never a tombstone — so a model with no
+ * `providerMergePolicy` rejects outright rather than running the fetch-order
+ * registers against a document whose liveness is governed by plain
+ * `$set`/`/` HLC registers instead.
+ */
+export declare function applyTombstoneMutation(ctx: MutationContext, mutation: TombstoneDocumentMutation): Promise<MutationApplyResult>;
+export declare function applyMutation(ctx: MutationContext, mutation: DocumentMutation): Promise<MutationApplyResult>;