@xnetjs/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -864,6 +864,61 @@ declare function validateExternalUrl(rawUrl: string): {
     error?: string;
 };
 
+/**
+ * The ONE Last-Write-Wins ordering for xNet (docs/specs/protocol §L1.7,
+ * exploration 0276).
+ *
+ * Per-property conflict resolution and change-log application ordering were
+ * previously re-implemented in three places (`NodeStore.applyChange`, the
+ * SQLite adapter's ON CONFLICT guards, and the hub storages' change
+ * ordering) — a drift class on the protocol's core convergence invariant.
+ * Every implementation now derives from this module, and the golden-vector
+ * conformance suite (exploration 0200) pins them equal.
+ *
+ * Ordering: lamport time, then wall time, then author DID compared by UTF-16
+ * code units. NEVER `localeCompare` — locale collation is non-deterministic
+ * across ICU versions and would break CRDT convergence (see the
+ * `0004-tie-author-case-codeunit` golden vector).
+ */
+/** The timestamp triple every LWW comparison runs on. */
+interface LwwStamp {
+    lamport: number;
+    wallTime: number;
+    author: string;
+}
+/**
+ * Spec comparator (§L1.7): negative when `a` loses to `b`, positive when `a`
+ * beats `b`, zero only for identical stamps.
+ */
+declare function compareLwwStamps(a: LwwStamp, b: LwwStamp): number;
+/** Whether an incoming write replaces the existing one under LWW. */
+declare function lwwWins(incoming: LwwStamp, existing: LwwStamp): boolean;
+/**
+ * Deterministic application order for change logs: lamport time, then author
+ * by code units. Used when replaying/relaying batches so every peer folds
+ * changes in the same sequence (matches the hub's
+ * `ORDER BY lamport_time ASC, lamport_author ASC`).
+ */
+declare function compareChangeApplicationOrder(a: {
+    lamport: number;
+    author: string;
+}, b: {
+    lamport: number;
+    author: string;
+}): number;
+/**
+ * SQL `ON CONFLICT … DO UPDATE … WHERE` guard implementing {@link lwwWins}
+ * inside SQLite (the `excluded.` pseudo-table is the incoming row). Column
+ * text comparison (`>`) is byte order under SQLite's default BINARY
+ * collation, which matches the code-unit rule for our ASCII DID strings.
+ */
+declare function lwwUpdateGuardSql(input: {
+    table: string;
+    lamportColumn: string;
+    wallTimeColumn: string;
+    authorColumn: string;
+}): string;
+
 /**
  * @xnetjs/core - Core types, schemas, and content addressing
  */
@@ -871,4 +926,4 @@ declare function validateExternalUrl(rawUrl: string): {
 type DID = `did:key:${string}`;
 type DocumentPath = `xnet://${DID}/workspace/${string}/doc/${string}`;
 
-export { ALL_CAPABILITIES, AUTH_ACTIONS, type ActionKey, type AllowExpr, type AndExpr, type AuthAction, type AuthCheckInput, type AuthDecision, type AuthDenyReason, type AuthExpression, type AuthTrace, type AuthTraceStep, type AuthenticatedExpr, type AuthorizationDefinition, BOOTSTRAP_PEERS, type Capability, type ChainStatus, type Condition, type ContentChunk, type ContentId, type ContentResolver, type ContentTree, type CreatorRoleResolver, DEFAULT_SNAPSHOT_TRIGGERS, DEFAULT_STREAMING_OPTIONS, DHT_CONFIG, type DID, type DIDResolution, type DIDResolver, type DataSource, type DenyExpr, type DocumentLoad, type DocumentPath, type Fork, type Group, type IPCondition, type MembershipRoleResolver, type MerkleNode, type NotExpr, type OrExpr, type PeerLocation, type PermissionEvaluator, type PermissionGrant, type PolicyEvaluator, type PropertyRoleResolver, type PublicExpr, type Query, type QueryPlan, type QueryRequest, type QueryResponse, type QueryRouter, RESOLUTION_CACHE_CONFIG, type RelationRoleResolver, type ResolutionStrategy, type ResourceScope, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type Snapshot, type SnapshotTriggers, SsrfError, type StreamingQueryOptions, type SubQuery, type TimeCondition, type UpdateVerifier, type VectorClock, assertPublicUrl, buildMerkleTree, clamp, clamp01, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, formatBytes, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isValidDID, isValidProgression, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, unionAggregate, validateExternalUrl, verifyContent, verifyUpdateChain };
+export { ALL_CAPABILITIES, AUTH_ACTIONS, type ActionKey, type AllowExpr, type AndExpr, type AuthAction, type AuthCheckInput, type AuthDecision, type AuthDenyReason, type AuthExpression, type AuthTrace, type AuthTraceStep, type AuthenticatedExpr, type AuthorizationDefinition, BOOTSTRAP_PEERS, type Capability, type ChainStatus, type Condition, type ContentChunk, type ContentId, type ContentResolver, type ContentTree, type CreatorRoleResolver, DEFAULT_SNAPSHOT_TRIGGERS, DEFAULT_STREAMING_OPTIONS, DHT_CONFIG, type DID, type DIDResolution, type DIDResolver, type DataSource, type DenyExpr, type DocumentLoad, type DocumentPath, type Fork, type Group, type IPCondition, type LwwStamp, type MembershipRoleResolver, type MerkleNode, type NotExpr, type OrExpr, type PeerLocation, type PermissionEvaluator, type PermissionGrant, type PolicyEvaluator, type PropertyRoleResolver, type PublicExpr, type Query, type QueryPlan, type QueryRequest, type QueryResponse, type QueryRouter, RESOLUTION_CACHE_CONFIG, type RelationRoleResolver, type ResolutionStrategy, type ResourceScope, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type Snapshot, type SnapshotTriggers, SsrfError, type StreamingQueryOptions, type SubQuery, type TimeCondition, type UpdateVerifier, type VectorClock, assertPublicUrl, buildMerkleTree, clamp, clamp01, compareChangeApplicationOrder, compareLwwStamps, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, formatBytes, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isValidDID, isValidProgression, lwwUpdateGuardSql, lwwWins, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, unionAggregate, validateExternalUrl, verifyContent, verifyUpdateChain };

package/dist/index.js

@@ -407,6 +407,28 @@ function validateExternalUrl(rawUrl) {
     return { valid: false, error: error instanceof Error ? error.message : "Invalid URL" };
   }
 }
+
+// src/lww.ts
+function compareLwwStamps(a, b) {
+  if (a.lamport !== b.lamport) return a.lamport - b.lamport;
+  if (a.wallTime !== b.wallTime) return a.wallTime - b.wallTime;
+  return a.author < b.author ? -1 : a.author > b.author ? 1 : 0;
+}
+function lwwWins(incoming, existing) {
+  return compareLwwStamps(incoming, existing) > 0;
+}
+function compareChangeApplicationOrder(a, b) {
+  if (a.lamport !== b.lamport) return a.lamport - b.lamport;
+  return a.author < b.author ? -1 : a.author > b.author ? 1 : 0;
+}
+function lwwUpdateGuardSql(input) {
+  const { table, lamportColumn, wallTimeColumn, authorColumn } = input;
+  return `excluded.${lamportColumn} > ${table}.${lamportColumn}
+            OR (excluded.${lamportColumn} = ${table}.${lamportColumn}
+                AND (excluded.${wallTimeColumn} > ${table}.${wallTimeColumn}
+                     OR (excluded.${wallTimeColumn} = ${table}.${wallTimeColumn}
+                         AND excluded.${authorColumn} > ${table}.${authorColumn})))`;
+}
 export {
   ALL_CAPABILITIES,
   AUTH_ACTIONS,
@@ -421,6 +443,8 @@ export {
   buildMerkleTree,
   clamp,
   clamp01,
+  compareChangeApplicationOrder,
+  compareLwwStamps,
   compareVectorClocks,
   createChunk,
   createContentId,
@@ -435,6 +459,8 @@ export {
   isLocationFresh,
   isValidDID,
   isValidProgression,
+  lwwUpdateGuardSql,
+  lwwWins,
   mergeStateVectors,
   mergeVectorClocks,
   parseContentId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",