@xnetjs/core 0.12.0 → 1.0.0

package/dist/index.d.ts

@@ -385,9 +385,13 @@ interface Role {
     capabilities: Capability[];
 }
 /**
- * Available capabilities
+ * Available capabilities.
+ *
+ * `create`/`update` are refinements of `write` (exploration 0304): a role
+ * holding `write` implicitly covers both; the granular capabilities cover
+ * only themselves.
  */
-type Capability = 'read' | 'write' | 'delete' | 'share' | 'admin';
+type Capability = 'read' | 'create' | 'update' | 'write' | 'delete' | 'share' | 'admin';
 /**
  * All capabilities in order of privilege
  */
@@ -451,7 +455,8 @@ interface PermissionEvaluator {
  */
 declare const STANDARD_ROLES: Record<string, Role>;
 /**
- * Check if a capability is included in a role
+ * Check if a capability is included in a role.
+ * A role holding `write` covers the `create`/`update` refinements.
  */
 declare function roleHasCapability(role: Role, capability: Capability): boolean;
 /**
@@ -483,12 +488,46 @@ type SchemaIRI = `xnet://${string}/${string}`;
 /**
  * Canonical authorization actions.
  * All action checks map to one of these values.
+ *
+ * `create` and `update` are refinements of the coarse `write` action
+ * (exploration 0304): `create` governs bringing a node into existence,
+ * `update` governs mutating a node that already exists. A schema MAY declare
+ * either refinement; when one is absent its expression falls back to the
+ * schema's `write` expression (see {@link actionExpressionOrder}), so schemas
+ * that only declare `write` behave exactly as before. Checking `write` on an
+ * existing node is equivalent to checking `update`.
+ *
+ * `create` checks evaluate roles against the *draft* node built from the
+ * create payload (`createdBy` = the caller). Because `role.creator()` then
+ * always matches, a schema that wants real admission control must exclude the
+ * creator role from `create` and require a container role instead — the
+ * draft's relation properties (e.g. `space`, `channel`) resolve normally.
  */
-declare const AUTH_ACTIONS: readonly ["read", "write", "delete", "share", "admin"];
+declare const AUTH_ACTIONS: readonly ["read", "create", "update", "write", "delete", "share", "admin"];
 /**
  * An authorization action that can be checked or granted.
  */
 type AuthAction = (typeof AUTH_ACTIONS)[number];
+/**
+ * Expression lookup order for a checked action — the first action name whose
+ * expression a schema defines wins (exploration 0304 fallback table):
+ *
+ * | checked            | expression used                     |
+ * |--------------------|-------------------------------------|
+ * | `create`           | `actions.create` ?? `actions.write` |
+ * | `update` / `write` | `actions.update` ?? `actions.write` |
+ * | anything else      | `actions[action]`                   |
+ */
+declare function actionExpressionOrder(action: AuthAction): readonly AuthAction[];
+/**
+ * Whether a granted action satisfies a checked action.
+ *
+ * A `write` grant covers its refinements (`create`, `update`); a granular
+ * grant covers only itself. A granular grant does NOT satisfy a legacy
+ * `write` check (fail closed — old callers checking `write` on an existing
+ * node mean update, which `update` covers).
+ */
+declare function grantActionSatisfies(granted: AuthAction, checked: AuthAction): boolean;
 /**
  * The result of an authorization check.
  * Contains whether access is allowed plus diagnostic info for debugging.
@@ -554,7 +593,11 @@ interface AuthTraceStep {
  *   },
  *   actions: {
  *     read: allow('editor', 'admin', 'owner'),
+ *     // coarse mutation policy; also the fallback for create/update
  *     write: allow('editor', 'admin', 'owner'),
+ *     // optional refinements (0304): who may add vs. who may modify
+ *     create: allow('editor', 'admin'),
+ *     update: allow('owner', 'admin'),
  *     delete: allow('admin', 'owner'),
  *     share: allow('admin', 'owner')
  *   },
@@ -865,14 +908,14 @@ declare function validateExternalUrl(rawUrl: string): {
 };
 
 /**
- * Retry/backoff policies (exploration 0300).
+ * Retry/backoff policies (exploration 0303).
  *
  * One dependency-free vocabulary for every reconnect/retry loop in the repo,
  * replacing the hand-rolled backoff math that had drifted into three parallel
  * implementations (sync connection-manager, WebSocketSyncProvider, webhook
  * emitter). Deliberately shaped like Effect's `Schedule` combinators so a
  * later migration would be mechanical — but scope-guarded: if this module
- * needs union/intersect/cron/hedging, stop and re-read exploration 0300.
+ * needs union/intersect/cron/hedging, stop and re-read exploration 0303.
  */
 /**
  * A retry policy maps a 1-based attempt number to the delay (in ms) to wait
@@ -902,7 +945,7 @@ declare function jittered(policy: RetryPolicy, ratio?: number, random?: () => nu
 declare function limitAttempts(policy: RetryPolicy, maxAttempts: number): RetryPolicy;
 
 /**
- * Tagged errors (exploration 0300).
+ * Tagged errors (exploration 0303).
  *
  * The repo-wide convention for structured errors, formalizing what
  * `NodeRelayError.code` and friends already did by hand: every structured
@@ -925,7 +968,7 @@ declare abstract class TaggedError<Tag extends string = string> extends Error {
 declare function isTagged<Tag extends string>(error: unknown, tag: Tag): error is TaggedError<Tag>;
 
 /**
- * Single-flight promise memoization (exploration 0300).
+ * Single-flight promise memoization (exploration 0303).
  *
  * The one implementation of the "share the in-flight promise so concurrent
  * callers don't convoy the backend" pattern that had been independently
@@ -954,27 +997,28 @@ interface SingleFlightOptions {
  */
 declare function singleFlight<K, V>(map: Map<K, Promise<V>>, key: K, fn: () => Promise<V>, options?: SingleFlightOptions): Promise<V>;
 
+/** Protocol version at which the grinding-resistant tiebreak key activates. */
+declare const LWW_TIEBREAK_KEY_VERSION = 4;
 /**
- * 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.
+ * The grinding-resistant LWW final tiebreak key (exploration 0305):
+ * `blake3_hex( author ‖ US ‖ propertyKey ‖ US ‖ canonicalJSON(value) )`.
  *
- * 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).
+ * Portable by construction — a kernel in any language reproduces it from
+ * canonical JSON of the value (which every kernel already computes for the
+ * change hash). A deletion (`value === undefined`) canonicalises as `null`.
  */
-/** The timestamp triple every LWW comparison runs on. */
+declare function computeLwwTiebreakKey(author: string, propertyKey: string, value: unknown): string;
+/** The timestamp every LWW comparison runs on. */
 interface LwwStamp {
     lamport: number;
     wallTime: number;
     author: string;
+    /**
+     * Grinding-resistant tiebreak key ({@link computeLwwTiebreakKey}), present
+     * only for changes at protocol version ≥ {@link LWW_TIEBREAK_KEY_VERSION}.
+     * Absent (legacy) stamps fall back to the author-DID tiebreak.
+     */
+    tiebreakKey?: string;
 }
 /**
  * Spec comparator (§L1.7): negative when `a` loses to `b`, positive when `a`
@@ -1000,13 +1044,22 @@ declare function compareChangeApplicationOrder(a: {
  * 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.
+ * collation, which matches the code-unit rule for our ASCII DID/hex strings.
+ *
+ * When `tiebreakKeyColumn` is supplied, the final rung mirrors
+ * {@link compareLwwStamps}: on a `lamport`+`wallTime` tie, if BOTH rows carry a
+ * non-null tiebreak key the larger key wins outright (author irrelevant);
+ * otherwise (either key null, or keys equal) the author DID decides. The stored
+ * key is precomputed in application code ({@link computeLwwTiebreakKey}), so SQL
+ * only ever compares the opaque hex — never recomputes it — keeping the JS and
+ * SQL paths byte-identical without a user-defined function.
  */
 declare function lwwUpdateGuardSql(input: {
     table: string;
     lamportColumn: string;
     wallTimeColumn: string;
     authorColumn: string;
+    tiebreakKeyColumn?: string;
 }): string;
 
 /**
@@ -1016,4 +1069,4 @@ declare function lwwUpdateGuardSql(input: {
 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 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 RetryPolicy, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type SingleFlightOptions, type Snapshot, type SnapshotTriggers, SsrfError, type StreamingQueryOptions, type SubQuery, TaggedError, type TimeCondition, type UpdateVerifier, type VectorClock, assertPublicUrl, buildMerkleTree, capped, clamp, clamp01, compareChangeApplicationOrder, compareLwwStamps, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, exponential, fixed, formatBytes, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isTagged, isValidDID, isValidProgression, jittered, limitAttempts, lwwUpdateGuardSql, lwwWins, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, singleFlight, 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, LWW_TIEBREAK_KEY_VERSION, 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 RetryPolicy, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type SingleFlightOptions, type Snapshot, type SnapshotTriggers, SsrfError, type StreamingQueryOptions, type SubQuery, TaggedError, type TimeCondition, type UpdateVerifier, type VectorClock, actionExpressionOrder, assertPublicUrl, buildMerkleTree, capped, clamp, clamp01, compareChangeApplicationOrder, compareLwwStamps, compareVectorClocks, computeLwwTiebreakKey, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, exponential, fixed, formatBytes, getMostPermissiveCapability, grantActionSatisfies, hashContent, incrementVectorClock, isLocationFresh, isTagged, isValidDID, isValidProgression, jittered, limitAttempts, lwwUpdateGuardSql, lwwWins, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, singleFlight, unionAggregate, validateExternalUrl, verifyContent, verifyUpdateChain };

package/dist/index.js

@@ -267,8 +267,38 @@ function deduplicatedUnion(results) {
   return output;
 }
 
+// src/auth-types.ts
+var AUTH_ACTIONS = [
+  "read",
+  "create",
+  "update",
+  "write",
+  "delete",
+  "share",
+  "admin"
+];
+function actionExpressionOrder(action) {
+  if (action === "create") return ["create", "write"];
+  if (action === "update" || action === "write") return ["update", "write"];
+  return [action];
+}
+function grantActionSatisfies(granted, checked) {
+  if (granted === checked) return true;
+  if (granted === "write") return checked === "create" || checked === "update";
+  if (granted === "update") return checked === "write";
+  return false;
+}
+
 // src/permissions.ts
-var ALL_CAPABILITIES = ["read", "write", "delete", "share", "admin"];
+var ALL_CAPABILITIES = [
+  "read",
+  "create",
+  "update",
+  "write",
+  "delete",
+  "share",
+  "admin"
+];
 var STANDARD_ROLES = {
   viewer: {
     id: "viewer",
@@ -284,7 +314,7 @@ var STANDARD_ROLES = {
   }
 };
 function roleHasCapability(role, capability) {
-  return role.capabilities.includes(capability);
+  return role.capabilities.some((held) => grantActionSatisfies(held, capability));
 }
 function evaluateCondition(condition, context) {
   switch (condition.type) {
@@ -306,9 +336,6 @@ function getMostPermissiveCapability(capabilities) {
   return null;
 }
 
-// src/auth-types.ts
-var AUTH_ACTIONS = ["read", "write", "delete", "share", "admin"];
-
 // src/utils/math.ts
 function clamp(value, min, max) {
   if (value < min) return min;
@@ -470,9 +497,36 @@ function singleFlight(map, key, fn, options = {}) {
 }
 
 // src/lww.ts
+import { blake3 as blake32 } from "@noble/hashes/blake3.js";
+var LWW_TIEBREAK_KEY_VERSION = 4;
+var US = "";
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    out[key] = canonicalize(value[key]);
+  }
+  return out;
+}
+function toHex(bytes) {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+function computeLwwTiebreakKey(author, propertyKey, value) {
+  const canonical = JSON.stringify(canonicalize(value === void 0 ? null : value));
+  const bytes = new TextEncoder().encode(`${author}${US}${propertyKey}${US}${canonical}`);
+  return toHex(blake32(bytes));
+}
 function compareLwwStamps(a, b) {
   if (a.lamport !== b.lamport) return a.lamport - b.lamport;
   if (a.wallTime !== b.wallTime) return a.wallTime - b.wallTime;
+  const aK = a.tiebreakKey;
+  const bK = b.tiebreakKey;
+  if (aK !== void 0 && bK !== void 0 && aK !== bK) {
+    return aK < bK ? -1 : 1;
+  }
   return a.author < b.author ? -1 : a.author > b.author ? 1 : 0;
 }
 function lwwWins(incoming, existing) {
@@ -483,12 +537,19 @@ function compareChangeApplicationOrder(a, b) {
   return a.author < b.author ? -1 : a.author > b.author ? 1 : 0;
 }
 function lwwUpdateGuardSql(input) {
-  const { table, lamportColumn, wallTimeColumn, authorColumn } = input;
+  const { table, lamportColumn, wallTimeColumn, authorColumn, tiebreakKeyColumn } = input;
+  const finalRung = tiebreakKeyColumn ? `(excluded.${tiebreakKeyColumn} IS NOT NULL
+                              AND ${table}.${tiebreakKeyColumn} IS NOT NULL
+                              AND excluded.${tiebreakKeyColumn} > ${table}.${tiebreakKeyColumn})
+                         OR (NOT (excluded.${tiebreakKeyColumn} IS NOT NULL
+                                  AND ${table}.${tiebreakKeyColumn} IS NOT NULL
+                                  AND excluded.${tiebreakKeyColumn} <> ${table}.${tiebreakKeyColumn})
+                             AND excluded.${authorColumn} > ${table}.${authorColumn})` : `excluded.${authorColumn} > ${table}.${authorColumn}`;
   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})))`;
+                         AND (${finalRung}))))`;
 }
 export {
   ALL_CAPABILITIES,
@@ -497,10 +558,12 @@ export {
   DEFAULT_SNAPSHOT_TRIGGERS,
   DEFAULT_STREAMING_OPTIONS,
   DHT_CONFIG,
+  LWW_TIEBREAK_KEY_VERSION,
   RESOLUTION_CACHE_CONFIG,
   STANDARD_ROLES,
   SsrfError,
   TaggedError,
+  actionExpressionOrder,
   assertPublicUrl,
   buildMerkleTree,
   capped,
@@ -509,6 +572,7 @@ export {
   compareChangeApplicationOrder,
   compareLwwStamps,
   compareVectorClocks,
+  computeLwwTiebreakKey,
   createChunk,
   createContentId,
   deduplicatedUnion,
@@ -519,6 +583,7 @@ export {
   fixed,
   formatBytes,
   getMostPermissiveCapability,
+  grantActionSatisfies,
   hashContent,
   incrementVectorClock,
   isLocationFresh,

package/package.json

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