@xnetjs/data 0.12.0 → 2.0.0

package/dist/{chunk-JFMLCFZJ.js → chunk-4S73XDWH.js}

@@ -8,11 +8,11 @@ import {
   SYSTEM_SCHEMA_BASE_IRIS,
   isSystemNamespaceResource,
   isSystemSchemaIri
-} from "./chunk-BY5O6LNC.js";
+} from "./chunk-XJBDESCX.js";
 import {
   createNodeId,
   getBaseSchemaIRI
-} from "./chunk-EBNMV2VO.js";
+} from "./chunk-RRXJNZX5.js";
 
 // src/store/query-ast.ts
 var QUERY_AST_VERSION = 1;
@@ -887,187 +887,23 @@ function evaluateQueryASTPlannerGate(value) {
 }
 
 // src/store/store.ts
-import { compareChangeApplicationOrder, lwwWins } from "@xnetjs/core";
-
-// src/store/transaction-executor.ts
-async function executeTransactionOperations(host, input) {
-  const results = [];
-  const changes = [];
-  const events = [];
-  for (let i = 0; i < input.operations.length; i++) {
-    const op = input.operations[i];
-    let change;
-    let result = null;
-    let previousNode = null;
-    switch (op.type) {
-      case "create": {
-        const id = op.options.id ?? createNodeId();
-        const payload = {
-          nodeId: id,
-          schemaId: op.options.schemaId,
-          properties: op.options.properties
-        };
-        change = await host.createBatchedChange(
-          "node-change",
-          payload,
-          input.lamport,
-          input.now,
-          input.batchId,
-          i,
-          input.batchSize,
-          input.storage
-        );
-        await host.applyChange(change, input.storage);
-        result = await input.storage.getNode(id);
-        await host.persistEncryptedNodeSnapshot(result, input.storage);
-        break;
-      }
-      case "update": {
-        const existing = host.cloneNodeState(await input.storage.getNode(op.nodeId));
-        if (!existing) {
-          throw new Error(`Node not found: ${op.nodeId}`);
-        }
-        previousNode = existing;
-        const payload = {
-          nodeId: op.nodeId,
-          properties: op.options.properties
-        };
-        change = await host.createBatchedChange(
-          "node-change",
-          payload,
-          input.lamport,
-          input.now,
-          input.batchId,
-          i,
-          input.batchSize,
-          input.storage
-        );
-        await host.applyChange(change, input.storage);
-        result = await input.storage.getNode(op.nodeId);
-        await host.persistEncryptedNodeSnapshot(result, input.storage);
-        break;
-      }
-      case "delete": {
-        const existing = host.cloneNodeState(await input.storage.getNode(op.nodeId));
-        if (!existing) {
-          throw new Error(`Node not found: ${op.nodeId}`);
-        }
-        previousNode = existing;
-        const payload = {
-          nodeId: op.nodeId,
-          properties: {},
-          deleted: true
-        };
-        change = await host.createBatchedChange(
-          "node-change",
-          payload,
-          input.lamport,
-          input.now,
-          input.batchId,
-          i,
-          input.batchSize,
-          input.storage
-        );
-        await host.applyChange(change, input.storage);
-        result = null;
-        break;
-      }
-      case "restore": {
-        const existing = host.cloneNodeState(await input.storage.getNode(op.nodeId));
-        if (!existing) {
-          throw new Error(`Node not found: ${op.nodeId}`);
-        }
-        previousNode = existing;
-        const payload = {
-          nodeId: op.nodeId,
-          properties: {},
-          deleted: false
-        };
-        change = await host.createBatchedChange(
-          "node-change",
-          payload,
-          input.lamport,
-          input.now,
-          input.batchId,
-          i,
-          input.batchSize,
-          input.storage
-        );
-        await host.applyChange(change, input.storage);
-        result = await input.storage.getNode(op.nodeId);
-        await host.persistEncryptedNodeSnapshot(result, input.storage);
-        break;
-      }
-    }
-    changes.push(change);
-    results.push(result);
-    events.push({ change, result, previousNode });
-  }
-  return { results, changes, events };
-}
-async function executeTransactionOperationsFast(host, input) {
-  const planned = input.operations.map((op) => ({
-    op,
-    id: op.type === "create" ? op.options.id ?? createNodeId() : op.nodeId
-  }));
-  const preflight = await host.getBatchPreflight(
-    planned.map((entry) => entry.id),
-    host.storage
-  );
-  const nodesById = host.cloneNodeMap(preflight.nodesById);
-  const lastChanges = new Map(preflight.lastChangesByNodeId);
-  const results = [];
-  const changes = [];
-  const events = [];
-  const affectedSchemaIds = /* @__PURE__ */ new Set();
-  for (let i = 0; i < planned.length; i++) {
-    const { op, id } = planned[i];
-    const existing = nodesById.get(id) ?? null;
-    if (op.type !== "create" && !existing) {
-      throw new Error(`Node not found: ${id}`);
-    }
-    const payload = op.type === "create" ? { nodeId: id, schemaId: op.options.schemaId, properties: op.options.properties } : op.type === "update" ? { nodeId: id, properties: op.options.properties } : { nodeId: id, properties: {}, deleted: op.type === "delete" };
-    const change = await host.createBatchedChangeWithParentHash(
-      "node-change",
-      payload,
-      lastChanges.get(id)?.hash ?? null,
-      input.lamport,
-      input.now,
-      input.batchId,
-      i,
-      input.batchSize
-    );
-    const schemaId = existing?.schemaId ?? (op.type === "create" ? op.options.schemaId : null);
-    if (!schemaId) {
-      throw new Error(`First change for node ${id} must include schemaId`);
-    }
-    const node = host.materializeNodeChange(
-      change,
-      existing ?? host.createInitialNodeFromChange(change, schemaId)
-    );
-    nodesById.set(id, node);
-    lastChanges.set(id, change);
-    affectedSchemaIds.add(schemaId);
-    changes.push(change);
-    const result = op.type === "delete" ? null : node;
-    results.push(result);
-    events.push({ change, result, previousNode: existing });
-  }
-  const touchedIds = Array.from(new Set(planned.map((entry) => entry.id)));
-  await host.storage.applyNodeBatch({
-    batchId: input.batchId,
-    nodes: touchedIds.flatMap((id) => {
-      const node = nodesById.get(id);
-      return node ? [node] : [];
-    }),
-    changes,
-    lastLamportTime: host.clockTime(),
-    affectedSchemaIds: Array.from(affectedSchemaIds),
-    indexMode: "touched",
-    indexProperties: true
-  });
-  return { results, changes, events };
-}
+import {
+  LWW_TIEBREAK_KEY_VERSION,
+  compareChangeApplicationOrder,
+  computeLwwTiebreakKey,
+  lwwWins
+} from "@xnetjs/core";
+import { base64ToBytes, bytesToBase64 } from "@xnetjs/crypto";
+import { parseDID } from "@xnetjs/identity";
+import {
+  createLamportClock,
+  tick,
+  receive,
+  signChange,
+  createUnsignedChange,
+  createBatchId
+} from "@xnetjs/sync";
+import { verifyChange, verifyChangeHash } from "@xnetjs/sync";
 
 // src/store/batch-write-orchestrator.ts
 var elapsedMs = (startedAt) => Math.max(0, Date.now() - startedAt);
@@ -1159,19 +995,6 @@ async function executeDeterministicNodeImport(host, input) {
   };
 }
 
-// src/store/store.ts
-import { base64ToBytes, bytesToBase64 } from "@xnetjs/crypto";
-import { parseDID } from "@xnetjs/identity";
-import {
-  createLamportClock,
-  tick,
-  receive,
-  signChange,
-  createUnsignedChange,
-  createBatchId
-} from "@xnetjs/sync";
-import { verifyChange, verifyChangeHash } from "@xnetjs/sync";
-
 // src/store/permission-error.ts
 import { TaggedError } from "@xnetjs/core";
 var PermissionError = class extends TaggedError {
@@ -1364,6 +1187,186 @@ function findSchemaIdForNode(operations, nodeId, tempIds) {
   return void 0;
 }
 
+// src/store/transaction-executor.ts
+async function executeTransactionOperations(host, input) {
+  const results = [];
+  const changes = [];
+  const events = [];
+  for (let i = 0; i < input.operations.length; i++) {
+    const op = input.operations[i];
+    let change;
+    let result = null;
+    let previousNode = null;
+    switch (op.type) {
+      case "create": {
+        const id = op.options.id ?? createNodeId();
+        const payload = {
+          nodeId: id,
+          schemaId: op.options.schemaId,
+          properties: op.options.properties
+        };
+        change = await host.createBatchedChange(
+          "node-change",
+          payload,
+          input.lamport,
+          input.now,
+          input.batchId,
+          i,
+          input.batchSize,
+          input.storage
+        );
+        await host.applyChange(change, input.storage);
+        result = await input.storage.getNode(id);
+        await host.persistEncryptedNodeSnapshot(result, input.storage);
+        break;
+      }
+      case "update": {
+        const existing = host.cloneNodeState(await input.storage.getNode(op.nodeId));
+        if (!existing) {
+          throw new Error(`Node not found: ${op.nodeId}`);
+        }
+        previousNode = existing;
+        const payload = {
+          nodeId: op.nodeId,
+          properties: op.options.properties
+        };
+        change = await host.createBatchedChange(
+          "node-change",
+          payload,
+          input.lamport,
+          input.now,
+          input.batchId,
+          i,
+          input.batchSize,
+          input.storage
+        );
+        await host.applyChange(change, input.storage);
+        result = await input.storage.getNode(op.nodeId);
+        await host.persistEncryptedNodeSnapshot(result, input.storage);
+        break;
+      }
+      case "delete": {
+        const existing = host.cloneNodeState(await input.storage.getNode(op.nodeId));
+        if (!existing) {
+          throw new Error(`Node not found: ${op.nodeId}`);
+        }
+        previousNode = existing;
+        const payload = {
+          nodeId: op.nodeId,
+          properties: {},
+          deleted: true
+        };
+        change = await host.createBatchedChange(
+          "node-change",
+          payload,
+          input.lamport,
+          input.now,
+          input.batchId,
+          i,
+          input.batchSize,
+          input.storage
+        );
+        await host.applyChange(change, input.storage);
+        result = null;
+        break;
+      }
+      case "restore": {
+        const existing = host.cloneNodeState(await input.storage.getNode(op.nodeId));
+        if (!existing) {
+          throw new Error(`Node not found: ${op.nodeId}`);
+        }
+        previousNode = existing;
+        const payload = {
+          nodeId: op.nodeId,
+          properties: {},
+          deleted: false
+        };
+        change = await host.createBatchedChange(
+          "node-change",
+          payload,
+          input.lamport,
+          input.now,
+          input.batchId,
+          i,
+          input.batchSize,
+          input.storage
+        );
+        await host.applyChange(change, input.storage);
+        result = await input.storage.getNode(op.nodeId);
+        await host.persistEncryptedNodeSnapshot(result, input.storage);
+        break;
+      }
+    }
+    changes.push(change);
+    results.push(result);
+    events.push({ change, result, previousNode });
+  }
+  return { results, changes, events };
+}
+async function executeTransactionOperationsFast(host, input) {
+  const planned = input.operations.map((op) => ({
+    op,
+    id: op.type === "create" ? op.options.id ?? createNodeId() : op.nodeId
+  }));
+  const preflight = await host.getBatchPreflight(
+    planned.map((entry) => entry.id),
+    host.storage
+  );
+  const nodesById = host.cloneNodeMap(preflight.nodesById);
+  const lastChanges = new Map(preflight.lastChangesByNodeId);
+  const results = [];
+  const changes = [];
+  const events = [];
+  const affectedSchemaIds = /* @__PURE__ */ new Set();
+  for (let i = 0; i < planned.length; i++) {
+    const { op, id } = planned[i];
+    const existing = nodesById.get(id) ?? null;
+    if (op.type !== "create" && !existing) {
+      throw new Error(`Node not found: ${id}`);
+    }
+    const payload = op.type === "create" ? { nodeId: id, schemaId: op.options.schemaId, properties: op.options.properties } : op.type === "update" ? { nodeId: id, properties: op.options.properties } : { nodeId: id, properties: {}, deleted: op.type === "delete" };
+    const change = await host.createBatchedChangeWithParentHash(
+      "node-change",
+      payload,
+      lastChanges.get(id)?.hash ?? null,
+      input.lamport,
+      input.now,
+      input.batchId,
+      i,
+      input.batchSize
+    );
+    const schemaId = existing?.schemaId ?? (op.type === "create" ? op.options.schemaId : null);
+    if (!schemaId) {
+      throw new Error(`First change for node ${id} must include schemaId`);
+    }
+    const node = host.materializeNodeChange(
+      change,
+      existing ?? host.createInitialNodeFromChange(change, schemaId)
+    );
+    nodesById.set(id, node);
+    lastChanges.set(id, change);
+    affectedSchemaIds.add(schemaId);
+    changes.push(change);
+    const result = op.type === "delete" ? null : node;
+    results.push(result);
+    events.push({ change, result, previousNode: existing });
+  }
+  const touchedIds = Array.from(new Set(planned.map((entry) => entry.id)));
+  await host.storage.applyNodeBatch({
+    batchId: input.batchId,
+    nodes: touchedIds.flatMap((id) => {
+      const node = nodesById.get(id);
+      return node ? [node] : [];
+    }),
+    changes,
+    lastLamportTime: host.clockTime(),
+    affectedSchemaIds: Array.from(affectedSchemaIds),
+    indexMode: "touched",
+    indexProperties: true
+  });
+  return { results, changes, events };
+}
+
 // src/store/store.ts
 var MAX_CONFLICTS = 200;
 var ENCRYPTED_NODE_MARKER = "xnet:node-encrypted:v1";
@@ -1390,6 +1393,14 @@ var NodeStore = class {
   listeners = /* @__PURE__ */ new Set();
   nodeListeners = /* @__PURE__ */ new Map();
   batchListeners = /* @__PURE__ */ new Set();
+  // Draft overlay (exploration 0329)
+  checkedOutDraft = null;
+  cloneToOriginal = /* @__PURE__ */ new Map();
+  draftMemberSet = /* @__PURE__ */ new Set();
+  draftDynamicMembers = false;
+  /** null = conservative "all schemas" (memberSchemaIds omitted). */
+  draftMemberSchemaSet = null;
+  draftOverlayListeners = /* @__PURE__ */ new Set();
   schemaLookup;
   propertyLookup;
   lensRegistry;
@@ -1463,12 +1474,13 @@ var NodeStore = class {
             schemaId: options.schemaId,
             properties: options.properties
           },
-          authAction: "write",
+          authAction: "create",
           requireExisting: false,
           createSchemaId: options.schemaId
         });
         this.emit(change2, node2, null, false);
         this.authEvaluator?.invalidate(node2.id);
+        this.notifyDraftNodeCreated(node2.id, node2.schemaId);
         if (this.telemetry) {
           this.telemetry.reportPerformance("data.create", Date.now() - start);
           this.telemetry.reportUsage("data.create", 1);
@@ -1477,7 +1489,7 @@ var NodeStore = class {
       }
       await this.assertAuthorized({
         subject: this.authorDID,
-        action: "write",
+        action: "create",
         nodeId: id,
         patch: options.properties,
         node: {
@@ -1504,6 +1516,7 @@ var NodeStore = class {
       await this.persistEncryptedNodeSnapshot(node);
       this.emit(change, node, null, false);
       this.authEvaluator?.invalidate(node.id);
+      this.notifyDraftNodeCreated(node.id, node.schemaId);
       if (this.telemetry) {
         this.telemetry.reportPerformance("data.create", Date.now() - start);
         this.telemetry.reportUsage("data.create", 1);
@@ -1520,10 +1533,186 @@ var NodeStore = class {
    * Get a Node by ID.
    */
   async get(id) {
+    const cloneId = this.checkedOutDraft?.clones[id];
+    if (cloneId) {
+      const clone = await this.getRaw(cloneId);
+      if (clone) return { ...clone, id };
+    }
+    return this.getRaw(id);
+  }
+  /**
+   * Read a node WITHOUT the draft overlay (exploration 0329) — merge review
+   * and diff surfaces use this to see main's true state while checked out.
+   */
+  async getRaw(id) {
     const node = await this.storage.getNode(id);
     const decrypted = await this.decryptNodeSnapshotIfPresent(node);
     return await this.canReadNode(decrypted) ? decrypted : null;
   }
+  // ==========================================================================
+  // Draft overlay (exploration 0329)
+  // ==========================================================================
+  /**
+   * Check a draft out (or pass null to return to main). While checked out,
+   * member reads swap to clone content under original ids, member writes
+   * redirect to clones (lazily forking via `onMissingMember`), and clone
+   * change events mirror to original-id subscribers.
+   */
+  setCheckedOutDraft(overlay) {
+    this.checkedOutDraft = overlay;
+    this.cloneToOriginal = new Map(
+      overlay ? Object.entries(overlay.clones).map(([orig, clone]) => [clone, orig]) : []
+    );
+    this.draftMemberSet = overlay && overlay.members !== "dynamic" ? new Set(overlay.members) : /* @__PURE__ */ new Set();
+    this.draftDynamicMembers = overlay?.members === "dynamic";
+    this.draftMemberSchemaSet = overlay?.memberSchemaIds ? new Set(overlay.memberSchemaIds) : null;
+    this.notifyDraftOverlayListeners();
+  }
+  /** Report a locally-created node to the checkout's draft-born hook (0329 P4). */
+  notifyDraftNodeCreated(nodeId, schemaId) {
+    const overlay = this.checkedOutDraft;
+    if (!overlay?.onNodeCreated) return;
+    if (nodeId === overlay.draftId || this.cloneToOriginal.has(nodeId)) return;
+    try {
+      overlay.onNodeCreated(nodeId, schemaId);
+    } catch (err) {
+      console.error("Error in draft onNodeCreated hook:", err);
+    }
+  }
+  notifyDraftOverlayListeners() {
+    for (const listener of this.draftOverlayListeners) {
+      try {
+        listener();
+      } catch (err) {
+        console.error("Error in draft overlay listener:", err);
+      }
+    }
+  }
+  getCheckedOutDraft() {
+    return this.checkedOutDraft;
+  }
+  /**
+   * Device-local draft privacy (exploration 0329): ids marked here (draft
+   * bookkeeping nodes, clones, draft-born nodes) are excluded from outbound
+   * sync publication by the personal node-sync room's `shouldPublish`
+   * predicate. In-memory only — the draft module rehydrates it from open
+   * Draft nodes at boot, BEFORE sync starts.
+   */
+  draftPrivateNodeIds = /* @__PURE__ */ new Set();
+  markDraftPrivate(ids) {
+    for (const id of ids) this.draftPrivateNodeIds.add(id);
+  }
+  unmarkDraftPrivate(ids) {
+    for (const id of ids) this.draftPrivateNodeIds.delete(id);
+  }
+  isDraftPrivate(id) {
+    return this.draftPrivateNodeIds.has(id);
+  }
+  /** Notified on every checkout change (including clone-map refreshes). */
+  subscribeToDraftOverlay(listener) {
+    this.draftOverlayListeners.add(listener);
+    return () => this.draftOverlayListeners.delete(listener);
+  }
+  /**
+   * Swap checked-out members' content to their clones (original ids kept, so
+   * MV id lists and grid ordering are untouched). No-op without a checkout.
+   */
+  async overlayStates(states) {
+    const overlay = this.checkedOutDraft;
+    if (!overlay) return states;
+    const visible = this.cloneToOriginal.size > 0 ? states.filter((state) => !this.cloneToOriginal.has(state.id)) : states;
+    const cloneIds = visible.map((s) => overlay.clones[s.id]).filter((cloneId) => cloneId !== void 0);
+    if (cloneIds.length === 0) return visible;
+    const cloneMap = await this.getNodesById(cloneIds, this.storage);
+    return Promise.all(
+      visible.map(async (state) => {
+        const cloneId = overlay.clones[state.id];
+        const clone = cloneId ? cloneMap.get(cloneId) : void 0;
+        if (!clone) return state;
+        const decrypted = await this.decryptNodeSnapshotIfPresent(clone);
+        return decrypted ? { ...decrypted, id: state.id } : state;
+      })
+    );
+  }
+  /**
+   * Draft-aware query path (0329 P5): candidates from storage WITHOUT
+   * pagination, unioned with checked-out members the predicate may have
+   * missed (their clone values can change membership), content-swapped,
+   * clone rows hidden, then the full descriptor re-applied in JS so
+   * filter/sort/pagination reflect draft values.
+   */
+  async draftAwareQuery(descriptor, start) {
+    const overlay = this.checkedOutDraft;
+    const unpaginated = withoutNodeQueryMaterializedView(withoutNodeQueryPagination(descriptor));
+    let candidates;
+    if (this.storage.queryNodes && !this.nodeContentCipher) {
+      candidates = (await this.storage.queryNodes(unpaginated)).nodes;
+    } else {
+      const fallback = await this.loadQueryFallbackCandidates(unpaginated);
+      const decrypted = await Promise.all(
+        fallback.nodes.map((node) => this.decryptNodeSnapshotIfPresent(node))
+      );
+      candidates = decrypted.filter((node) => node !== null);
+    }
+    if (overlay) {
+      const present = new Set(candidates.map((node) => node.id));
+      const missing = Object.keys(overlay.clones).filter(
+        (id) => !present.has(id)
+      );
+      if (missing.length > 0) {
+        const extra = await this.getNodesById(missing, this.storage);
+        for (const node of extra.values()) {
+          const decrypted = await this.decryptNodeSnapshotIfPresent(node);
+          if (!decrypted) continue;
+          if (decrypted.schemaId !== descriptor.schemaId) continue;
+          if (decrypted.deleted && !descriptor.includeDeleted) continue;
+          candidates.push(decrypted);
+        }
+      }
+    }
+    const readable = await this.filterReadableNodes(candidates);
+    const swapped = await this.overlayStates(readable);
+    const filtered = applyNodeQueryDescriptor(swapped, withoutNodeQueryPagination(descriptor));
+    const result = applyNodeQueryDescriptor(swapped, descriptor);
+    return {
+      nodes: result,
+      totalCount: filtered.length,
+      plan: {
+        strategy: "draft-overlay",
+        candidateNodeCount: readable.length,
+        hydratedNodeCount: swapped.length,
+        returnedNodeCount: result.length,
+        durationMs: Date.now() - start
+      }
+    };
+  }
+  /**
+   * Resolve where a write to `id` lands under the checkout: an existing
+   * clone, a lazily-forked one (`onMissingMember`), or — for non-members,
+   * clone ids, and declined forks — the id itself.
+   */
+  async resolveDraftWriteTarget(id) {
+    const overlay = this.checkedOutDraft;
+    if (!overlay) return id;
+    const existing = overlay.clones[id];
+    if (existing) return existing;
+    if (this.draftDynamicMembers) {
+      if (id === overlay.draftId || this.cloneToOriginal.has(id)) return id;
+    } else if (!this.draftMemberSet.has(id)) {
+      return id;
+    }
+    if (overlay.onMissingMember) {
+      const cloneId = await overlay.onMissingMember(id);
+      if (cloneId && this.checkedOutDraft === overlay) {
+        this.checkedOutDraft = { ...overlay, clones: { ...overlay.clones, [id]: cloneId } };
+        this.cloneToOriginal.set(cloneId, id);
+        this.notifyDraftOverlayListeners();
+        return cloneId;
+      }
+      if (cloneId) return cloneId;
+    }
+    return id;
+  }
   /**
    * Return the subset of IDs that already exist in materialized storage.
    *
@@ -1603,6 +1792,7 @@ var NodeStore = class {
    */
   async update(id, options) {
     const start = this.telemetry ? Date.now() : 0;
+    id = await this.resolveDraftWriteTarget(id);
     try {
       if (this.canUseSingleWriteFastPath()) {
         const { node: node2, previousNode, change: change2 } = await this.applySingleNodeWrite({
@@ -1611,7 +1801,7 @@ var NodeStore = class {
             nodeId: id,
             properties: options.properties
           },
-          authAction: "write",
+          authAction: "update",
           requireExisting: true
         });
         this.emit(change2, node2, previousNode, false);
@@ -1635,7 +1825,7 @@ var NodeStore = class {
       }
       await this.assertAuthorized({
         subject: this.authorDID,
-        action: "write",
+        action: "update",
         nodeId: id,
         patch: options.properties,
         node: {
@@ -1685,6 +1875,7 @@ var NodeStore = class {
    */
   async delete(id) {
     const start = this.telemetry ? Date.now() : 0;
+    id = await this.resolveDraftWriteTarget(id);
     try {
       if (this.canUseSingleWriteFastPath()) {
         const { node, previousNode, change: change2 } = await this.applySingleNodeWrite({
@@ -1750,6 +1941,7 @@ var NodeStore = class {
    * Restore a deleted Node.
    */
   async restore(id) {
+    id = await this.resolveDraftWriteTarget(id);
     if (this.canUseSingleWriteFastPath()) {
       const { node: node2, previousNode, change: change2 } = await this.applySingleNodeWrite({
         nodeId: id,
@@ -1758,7 +1950,7 @@ var NodeStore = class {
           properties: {},
           deleted: false
         },
-        authAction: "write",
+        authAction: "update",
         requireExisting: true
       });
       this.emit(change2, node2, previousNode, false);
@@ -1771,7 +1963,7 @@ var NodeStore = class {
     }
     await this.assertAuthorized({
       subject: this.authorDID,
-      action: "write",
+      action: "update",
       nodeId: id,
       node: {
         schemaId: existing.schemaId,
@@ -1818,7 +2010,8 @@ var NodeStore = class {
       const readable = await this.filterReadableNodes(
         decrypted.filter((node) => node !== null)
       );
-      const result = this.authEvaluator ? this.applyListPagination(readable, options) : readable;
+      const paged = this.authEvaluator ? this.applyListPagination(readable, options) : readable;
+      const result = await this.overlayStates(paged);
       if (this.telemetry) {
         this.telemetry.reportPerformance("data.list", Date.now() - start);
         this.telemetry.reportUsage("data.list", 1);
@@ -1837,10 +2030,13 @@ var NodeStore = class {
   async query(descriptor) {
     const start = Date.now();
     try {
+      if (this.checkedOutDraft && Object.keys(this.checkedOutDraft.clones).length > 0 && (this.draftMemberSchemaSet === null || this.draftMemberSchemaSet.has(descriptor.schemaId))) {
+        return this.draftAwareQuery(descriptor, start);
+      }
       if (this.storage.queryNodes && !this.nodeContentCipher && !this.authEvaluator) {
         const result2 = await this.storage.queryNodes(descriptor);
         return {
-          nodes: result2.nodes,
+          nodes: await this.overlayStates(result2.nodes),
           totalCount: result2.totalCount,
           plan: {
             ...result2.plan,
@@ -1852,7 +2048,7 @@ var NodeStore = class {
         const authFingerprint = await this.authFingerprint();
         const result2 = await this.storage.queryNodes({ ...descriptor, authFingerprint });
         return {
-          nodes: result2.nodes,
+          nodes: await this.overlayStates(result2.nodes),
           totalCount: result2.totalCount,
           plan: {
             ...result2.plan,
@@ -1863,7 +2059,7 @@ var NodeStore = class {
       if (this.storage.queryNodes && !this.nodeContentCipher && this.authEvaluator && !descriptor.nodeId && descriptor.materializedView === void 0) {
         const candidates = await this.storage.queryNodes(withoutNodeQueryPagination(descriptor));
         const readable2 = await this.filterReadableNodes(candidates.nodes);
-        const result2 = applyNodeQueryDescriptor(readable2, descriptor);
+        const result2 = await this.overlayStates(applyNodeQueryDescriptor(readable2, descriptor));
         return {
           nodes: result2,
           totalCount: readable2.length,
@@ -1887,7 +2083,9 @@ var NodeStore = class {
       const readable = await this.filterReadableNodes(
         decrypted.filter((node) => node !== null)
       );
-      const result = applyNodeQueryDescriptor(readable, fallback.postFilterDescriptor);
+      const result = await this.overlayStates(
+        applyNodeQueryDescriptor(readable, fallback.postFilterDescriptor)
+      );
       const totalCount = fallback.totalCount ?? (fallback.paginatedInStorage ? void 0 : applyNodeQueryDescriptor(
         readable,
         withoutNodeQueryPagination(fallback.postFilterDescriptor)
@@ -2472,12 +2670,21 @@ var NodeStore = class {
         );
       }
       if (this.authEvaluator) {
-        const action = this.inferActionFromChange(change);
+        const stored = await this.storage.getNode(change.payload.nodeId);
+        const action = this.inferActionFromChange(change, stored);
         const decision = await this.authEvaluator.can({
           subject: change.authorDID,
           action,
           nodeId: change.payload.nodeId,
-          patch: action === "write" ? change.payload.properties : void 0
+          patch: action === "create" || action === "update" ? change.payload.properties : void 0,
+          // A remote create has no stored node to evaluate against — build the
+          // draft from the payload so container-relation roles resolve
+          // (exploration 0304). Update/delete load the stored node as before.
+          node: action === "create" && change.payload.schemaId ? {
+            schemaId: change.payload.schemaId,
+            createdBy: change.authorDID,
+            properties: change.payload.properties
+          } : void 0
         });
         if (!decision.allowed) {
           this.telemetry?.reportSecurityEvent("data.unauthorized_remote_change", "medium");
@@ -2673,6 +2880,24 @@ var NodeStore = class {
         }
       }
     }
+    const originalId = this.cloneToOriginal.get(change.payload.nodeId);
+    if (originalId) {
+      const originalListeners = this.nodeListeners.get(originalId);
+      if (originalListeners) {
+        const mirrored = {
+          ...event,
+          node: event.node ? { ...event.node, id: originalId } : event.node,
+          previousNode: event.previousNode ? { ...event.previousNode, id: originalId } : event.previousNode
+        };
+        for (const listener of originalListeners) {
+          try {
+            listener(mirrored);
+          } catch (err) {
+            console.error("Error in NodeStore draft-mirror listener:", err);
+          }
+        }
+      }
+    }
   }
   // ==========================================================================
   // Internal Methods
@@ -2922,7 +3147,11 @@ var NodeStore = class {
     const newTs = {
       lamport: change.lamport,
       author: change.authorDID,
-      wallTime: change.wallTime
+      wallTime: change.wallTime,
+      // Grinding-resistant final tiebreak (exploration 0305): only v4+ changes
+      // carry a key, so a v4-vs-legacy comparison degrades to the author DID
+      // and mixed fleets still agree.
+      ...(change.protocolVersion ?? 0) >= LWW_TIEBREAK_KEY_VERSION ? { tiebreakKey: computeLwwTiebreakKey(change.authorDID, key, value) } : {}
     };
     const incomingWins = !existingTs || this.shouldReplace(existingTs, newTs);
     const target = isUnknownProperty ? node._unknown ??= {} : node.properties;
@@ -3057,7 +3286,7 @@ var NodeStore = class {
       if (operation.type === "create") {
         await this.assertAuthorized({
           subject: this.authorDID,
-          action: "write",
+          action: "create",
           nodeId: operation.options.id ?? "",
           node: {
             schemaId: operation.options.schemaId,
@@ -3077,17 +3306,20 @@ var NodeStore = class {
       }
       await this.assertAuthorized({
         subject: this.authorDID,
-        action: "write",
+        action: "update",
         nodeId: operation.nodeId,
         patch: operation.type === "update" ? operation.options.properties : void 0
       });
     }
   }
-  inferActionFromChange(change) {
+  inferActionFromChange(change, stored) {
     if (change.payload.deleted === true) {
       return "delete";
     }
-    return "write";
+    if (!stored && change.payload.schemaId) {
+      return "create";
+    }
+    return "update";
   }
   shouldRecomputeRecipients(schemaId, patch) {
     const authRelevant = this.authRelevantPropertyLookup?.(schemaId);
@@ -3396,6 +3628,41 @@ var MemoryNodeStorageAdapter = class {
     this.yjsSnapshotStore = this.yjsSnapshotStore.filter((s) => s.nodeId !== nodeId);
   }
   // ==========================================================================
+  // Pin Registry (exploration 0329)
+  // ==========================================================================
+  /** key -> ownerId -> entry */
+  pinStore = /* @__PURE__ */ new Map();
+  pins = {
+    addPins: async (pins) => {
+      for (const pin of pins) {
+        let owners = this.pinStore.get(pin.key);
+        if (!owners) {
+          owners = /* @__PURE__ */ new Map();
+          this.pinStore.set(pin.key, owners);
+        }
+        owners.set(pin.ownerId, { ...pin });
+      }
+    },
+    removePinsByOwner: async (ownerId) => {
+      for (const [key, owners] of this.pinStore) {
+        owners.delete(ownerId);
+        if (owners.size === 0) this.pinStore.delete(key);
+      }
+    },
+    getPinnedKeysAmong: async (keys) => {
+      const pinned = /* @__PURE__ */ new Set();
+      for (const key of keys) {
+        if (this.pinStore.has(key)) pinned.add(key);
+      }
+      return pinned;
+    },
+    countPins: async () => {
+      let count2 = 0;
+      for (const owners of this.pinStore.values()) count2 += owners.size;
+      return count2;
+    }
+  };
+  // ==========================================================================
   // Utility Methods (for testing)
   // ==========================================================================
   /**
@@ -3407,6 +3674,7 @@ var MemoryNodeStorageAdapter = class {
     this.nodes.clear();
     this.documentContentStore.clear();
     this.yjsSnapshotStore = [];
+    this.pinStore.clear();
     this.lastLamportTime = 0;
     this.syncCursors.clear();
   }
@@ -3446,6 +3714,9 @@ var MemoryNodeStorageAdapter = class {
         ])
       ),
       yjsSnapshotStore: structuredClone(this.yjsSnapshotStore),
+      pinStore: new Map(
+        Array.from(this.pinStore.entries(), ([key, owners]) => [key, new Map(owners)])
+      ),
       lastLamportTime: this.lastLamportTime
     };
   }
@@ -3455,6 +3726,7 @@ var MemoryNodeStorageAdapter = class {
     this.nodes = snapshot.nodes;
     this.documentContentStore = snapshot.documentContentStore;
     this.yjsSnapshotStore = snapshot.yjsSnapshotStore;
+    this.pinStore = snapshot.pinStore;
     this.lastLamportTime = snapshot.lastLamportTime;
   }
 };
@@ -3520,7 +3792,10 @@ function hydrateJoinedRows(rows) {
       node.timestamps[row.property_key] = {
         lamport: row.lamport_time ?? 0,
         author: row.updated_by ?? "",
-        wallTime: row.prop_updated_at ?? 0
+        wallTime: row.prop_updated_at ?? 0,
+        // Round-trip the stored key so the in-memory LWW comparison matches the
+        // SQL guard exactly (0305); NULL legacy rows keep the author tiebreak.
+        ...row.tiebreak_key != null ? { tiebreakKey: row.tiebreak_key } : {}
       };
       if ((row.prop_updated_at ?? 0) >= node.updatedAt) {
         node.updatedBy = row.updated_by ?? node.createdBy;
@@ -3540,7 +3815,10 @@ function hydrateAggregatedRows(rows) {
       timestamps[key] = {
         lamport: entry.l ?? 0,
         author: entry.b ?? "",
-        wallTime: entry.w ?? 0
+        wallTime: entry.w ?? 0,
+        // Round-trip the stored tiebreak key (0305) so aggregated hydrate
+        // matches the SQL guard; NULL/absent → author tiebreak.
+        ...entry.k != null ? { tiebreakKey: entry.k } : {}
       };
       if ((entry.w ?? 0) >= row.updated_at) {
         node.updatedBy = entry.b ?? row.created_by;
@@ -3571,6 +3849,7 @@ function buildHydrateChunkQuery(ids) {
         p.lamport_time,
         p.updated_by,
         p.updated_at AS prop_updated_at,
+        p.tiebreak_key,
         wanted.ordinal
       FROM wanted
       JOIN nodes n ON n.id = wanted.id
@@ -3599,7 +3878,7 @@ function buildAggregatedHydrateChunkQuery(ids) {
           FILTER (WHERE p.property_key IS NOT NULL) AS props_json,
         json_group_object(
           p.property_key,
-          json_object('l', p.lamport_time, 'b', p.updated_by, 'w', p.updated_at)
+          json_object('l', p.lamport_time, 'b', p.updated_by, 'w', p.updated_at, 'k', p.tiebreak_key)
         ) FILTER (WHERE p.property_key IS NOT NULL) AS meta_json
       FROM wanted
       JOIN nodes n ON n.id = wanted.id
@@ -4522,7 +4801,12 @@ var NODE_PROPERTIES_LWW_GUARD = lwwUpdateGuardSql({
   table: "node_properties",
   lamportColumn: "lamport_time",
   wallTimeColumn: "updated_at",
-  authorColumn: "updated_by"
+  authorColumn: "updated_by",
+  // Grinding-resistant final tiebreak (exploration 0305): larger key wins when
+  // both rows carry one (v4+), else the author DID. The key is precomputed in
+  // application code and stored, so SQL only compares the opaque hex — byte
+  // identical to `shouldReplace` in ./store.ts, no user-defined function.
+  tiebreakKeyColumn: "tiebreak_key"
 });
 var DEFAULT_ADAPTIVE_INDEXING = {
   enabled: false,
@@ -4622,6 +4906,7 @@ var SQLiteNodeStorageAdapter = class {
   nodeReadAuthorizer;
   /** One-time guard: ensure the `auth_fingerprint` column exists on upgraded DBs. */
   materializationColumnsReady = false;
+  nodePropertyColumnsReady = null;
   /**
    * Descriptor→SQL compilation lives in `query-compiler.ts` (exploration
    * 0276). Flags are read per-compile so the compiler never captures stale
@@ -4916,12 +5201,14 @@ var SQLiteNodeStorageAdapter = class {
   }
   // ─── Materialized State Operations ────────────────────────────────────────
   async getNode(id) {
+    await this.ensureNodePropertyColumns();
     const nodes = await hydrateNodesByIds(this.db, [id], this.aggregatedHydration);
     return nodes[0] ?? null;
   }
   async getNodes(ids) {
     const uniqueIds = Array.from(new Set(ids));
     if (uniqueIds.length === 0) return [];
+    await this.ensureNodePropertyColumns();
     return hydrateNodesByIds(this.db, uniqueIds, this.aggregatedHydration);
   }
   async getExistingNodeIds(ids) {
@@ -4966,6 +5253,7 @@ var SQLiteNodeStorageAdapter = class {
    * Used by importNodes to avoid nested transactions.
    */
   async _setNodeInternal(node, options) {
+    await this.ensureNodePropertyColumns();
     await this.db.run(
       `INSERT INTO nodes (id, schema_id, created_at, updated_at, created_by, deleted_at)
        VALUES (?, ?, ?, ?, ?, ?)
@@ -4987,13 +5275,14 @@ var SQLiteNodeStorageAdapter = class {
       const timestamp = node.timestamps[key];
       if (!timestamp) continue;
       await this.db.run(
-        `INSERT INTO node_properties (node_id, property_key, value, lamport_time, updated_by, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)
+        `INSERT INTO node_properties (node_id, property_key, value, lamport_time, updated_by, updated_at, tiebreak_key)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(node_id, property_key) DO UPDATE SET
            value = excluded.value,
            lamport_time = excluded.lamport_time,
            updated_by = excluded.updated_by,
-           updated_at = excluded.updated_at
+           updated_at = excluded.updated_at,
+           tiebreak_key = excluded.tiebreak_key
          WHERE ${NODE_PROPERTIES_LWW_GUARD}`,
         [
           node.id,
@@ -5001,7 +5290,8 @@ var SQLiteNodeStorageAdapter = class {
           this.serializeValue(value),
           timestamp.lamport,
           timestamp.author,
-          timestamp.wallTime
+          timestamp.wallTime,
+          timestamp.tiebreakKey ?? null
         ]
       );
     }
@@ -5040,6 +5330,7 @@ var SQLiteNodeStorageAdapter = class {
    * Fetches nodes and properties in one query for better performance with large datasets.
    */
   async listNodesOptimized(options) {
+    await this.ensureNodePropertyColumns();
     let whereClause = "1=1";
     const params = [];
     if (options?.schemaId) {
@@ -5063,7 +5354,7 @@ var SQLiteNodeStorageAdapter = class {
         )
         SELECT 
           ln.id, ln.schema_id, ln.created_at, ln.updated_at, ln.created_by, ln.deleted_at,
-          p.property_key, p.value, p.lamport_time, p.updated_by, p.updated_at as prop_updated_at,
+          p.property_key, p.value, p.lamport_time, p.updated_by, p.updated_at as prop_updated_at, p.tiebreak_key,
           NULL as ordinal
         FROM limited_nodes ln
         LEFT JOIN node_properties p ON ln.id = p.node_id
@@ -5075,7 +5366,7 @@ var SQLiteNodeStorageAdapter = class {
       sql = `
         SELECT 
           n.id, n.schema_id, n.created_at, n.updated_at, n.created_by, n.deleted_at,
-          p.property_key, p.value, p.lamport_time, p.updated_by, p.updated_at as prop_updated_at,
+          p.property_key, p.value, p.lamport_time, p.updated_by, p.updated_at as prop_updated_at, p.tiebreak_key,
           NULL as ordinal
         FROM nodes n
         LEFT JOIN node_properties p ON n.id = p.node_id
@@ -5101,6 +5392,7 @@ var SQLiteNodeStorageAdapter = class {
   }
   async queryNodes(descriptor) {
     const start = Date.now();
+    await this.ensureNodePropertyColumns();
     if (descriptor.materializedView) {
       return this.queryMaterializedView(descriptor, start);
     }
@@ -5291,6 +5583,47 @@ var SQLiteNodeStorageAdapter = class {
       [nodeId, content, Date.now()]
     );
   }
+  // ─── Pin Registry (exploration 0329) ──────────────────────────────────────
+  pins = {
+    addPins: async (pins) => {
+      if (pins.length === 0) return;
+      await this.enqueueWrite(async () => {
+        const now = Date.now();
+        for (const chunk of chunkItems(pins, 200)) {
+          const placeholders = chunk.map(() => "(?, ?, ?, ?)").join(", ");
+          const params = [];
+          for (const pin of chunk) params.push(pin.key, pin.ownerId, pin.reason, now);
+          await this.db.run(
+            `INSERT INTO pinned_changes (pin_key, owner_id, reason, created_at)
+             VALUES ${placeholders}
+             ON CONFLICT(pin_key, owner_id) DO NOTHING`,
+            params
+          );
+        }
+      });
+    },
+    removePinsByOwner: async (ownerId) => {
+      await this.enqueueWrite(async () => {
+        await this.db.run(`DELETE FROM pinned_changes WHERE owner_id = ?`, [ownerId]);
+      });
+    },
+    getPinnedKeysAmong: async (keys) => {
+      const pinned = /* @__PURE__ */ new Set();
+      for (const chunk of chunkItems(keys, 500)) {
+        const placeholders = chunk.map(() => "?").join(", ");
+        const rows = await this.db.query(
+          `SELECT DISTINCT pin_key FROM pinned_changes WHERE pin_key IN (${placeholders})`,
+          [...chunk]
+        );
+        for (const row of rows) pinned.add(row.pin_key);
+      }
+      return pinned;
+    },
+    countPins: async () => {
+      const row = await this.db.queryOne(`SELECT COUNT(*) AS n FROM pinned_changes`);
+      return row?.n ?? 0;
+    }
+  };
   // ─── Yjs Snapshots (Extended) ─────────────────────────────────────────────
   /**
    * Save a Yjs snapshot for time travel.
@@ -5588,6 +5921,7 @@ var SQLiteNodeStorageAdapter = class {
     if (!this.db.transactionBatch) {
       throw new Error("SQLite transactionBatch is not available.");
     }
+    await this.ensureNodePropertyColumns();
     const operations = [];
     const indexProperties = options?.indexProperties ?? true;
     const hasFullTextSearch = await this.fullTextIndexing.hasTable();
@@ -5638,16 +5972,17 @@ var SQLiteNodeStorageAdapter = class {
       const timestamp = node.timestamps[key];
       if (!timestamp) continue;
       operations.push({
-        // Full LWW ordering triple — keep in lockstep with the setNode
-        // upsert above and `shouldReplace` in ./store.ts (0272).
+        // Full LWW ordering chain — keep in lockstep with the setNode
+        // upsert above and `shouldReplace` in ./store.ts (0272/0305).
         sql: `INSERT INTO node_properties
-                (node_id, property_key, value, lamport_time, updated_by, updated_at)
-              VALUES (?, ?, ?, ?, ?, ?)
+                (node_id, property_key, value, lamport_time, updated_by, updated_at, tiebreak_key)
+              VALUES (?, ?, ?, ?, ?, ?, ?)
               ON CONFLICT(node_id, property_key) DO UPDATE SET
                 value = excluded.value,
                 lamport_time = excluded.lamport_time,
                 updated_by = excluded.updated_by,
-                updated_at = excluded.updated_at
+                updated_at = excluded.updated_at,
+                tiebreak_key = excluded.tiebreak_key
               WHERE ${NODE_PROPERTIES_LWW_GUARD}`,
         params: [
           node.id,
@@ -5655,7 +5990,8 @@ var SQLiteNodeStorageAdapter = class {
           this.serializeValue(value),
           timestamp.lamport,
           timestamp.author,
-          timestamp.wallTime
+          timestamp.wallTime,
+          timestamp.tiebreakKey ?? null
         ]
       });
     }
@@ -5907,6 +6243,25 @@ var SQLiteNodeStorageAdapter = class {
     }
     this.materializationColumnsReady = true;
   }
+  /**
+   * Ensure the `node_properties.tiebreak_key` column exists (exploration 0305).
+   * Fresh databases get it from the DDL; databases created before schema v8 need
+   * this in-place add so the grinding-resistant LWW guard has a column to
+   * compare. Idempotent, memoized, and non-fatal on races — a legacy NULL key
+   * just falls back to the author-DID tiebreak.
+   */
+  async ensureNodePropertyColumns() {
+    this.nodePropertyColumnsReady ??= (async () => {
+      try {
+        const columns = await this.db.query(`PRAGMA table_info(node_properties)`);
+        if (!columns.some((column) => column.name === "tiebreak_key")) {
+          await this.db.run("ALTER TABLE node_properties ADD COLUMN tiebreak_key TEXT");
+        }
+      } catch {
+      }
+    })();
+    return this.nodePropertyColumnsReady;
+  }
   setNodeReadAuthorizer(authorizer) {
     this.nodeReadAuthorizer = authorizer;
   }