@xnetjs/data 0.0.3 → 0.1.1

package/dist/{chunk-QVZXXJSP.js → chunk-EI5CY2FZ.js}

@@ -3,15 +3,16 @@ import {
   getNodeQuerySearchTokens,
   withoutNodeQueryMaterializedView,
   withoutNodeQueryPagination
-} from "./chunk-S4B5OPZU.js";
+} from "./chunk-S5RP5RKY.js";
 import {
+  SYSTEM_SCHEMA_BASE_IRIS,
   isSystemNamespaceResource,
   isSystemSchemaIri
-} from "./chunk-V6HZ3LF3.js";
+} from "./chunk-BY5O6LNC.js";
 import {
   createNodeId,
   getBaseSchemaIRI
-} from "./chunk-O64EK5FK.js";
+} from "./chunk-EBNMV2VO.js";
 
 // src/store/query-ast.ts
 var QUERY_AST_VERSION = 1;
@@ -1142,6 +1143,9 @@ var NodeStore = class {
     this.onUnauthorizedRemoteChange = options.onUnauthorizedRemoteChange;
     this.auth = options.auth;
     this.telemetry = options.telemetry;
+    if (this.authEvaluator && this.storage.setNodeReadAuthorizer) {
+      this.storage.setNodeReadAuthorizer((nodes) => this.filterReadableNodes(nodes));
+    }
   }
   /**
    * Initialize the store by loading the last Lamport time from storage.
@@ -1569,6 +1573,18 @@ var NodeStore = class {
           }
         };
       }
+      if (this.storage.queryNodes && !this.nodeContentCipher && this.authEvaluator && !descriptor.nodeId && descriptor.materializedView !== void 0 && this.materializedAuthSupported()) {
+        const authFingerprint = await this.authFingerprint();
+        const result2 = await this.storage.queryNodes({ ...descriptor, authFingerprint });
+        return {
+          nodes: result2.nodes,
+          totalCount: result2.totalCount,
+          plan: {
+            ...result2.plan,
+            durationMs: Date.now() - start
+          }
+        };
+      }
       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);
@@ -2926,6 +2942,31 @@ var NodeStore = class {
     const decisions = await Promise.all(nodes.map((node) => this.canReadNode(node)));
     return nodes.filter((_, index) => decisions[index]);
   }
+  /**
+   * Whether storage can safely materialize a view under read authorization
+   * (exploration 0226): it must both accept the read authorizer (to authorize
+   * the id list at refresh) and expose a reload-stable authorization-state
+   * version (to fingerprint cache validity). When either is missing the store
+   * falls back to the authorize-then-paginate path, which never caches.
+   */
+  materializedAuthSupported() {
+    return Boolean(this.storage.setNodeReadAuthorizer && this.storage.getAuthorizationStateVersion);
+  }
+  /**
+   * A reload-stable fingerprint of the viewer's authorization context, folded
+   * from the subject DID and the control-plane (grant) state version. Stamped
+   * onto a materialized view so any grant change forces an `'authz-changed'`
+   * refresh — the cache can never serve rows a revoked viewer may no longer
+   * read. Returns `undefined` when authorization is off (materialized views run
+   * untouched, as in the trusted single-user case).
+   */
+  async authFingerprint() {
+    if (!this.authEvaluator || !this.storage.getAuthorizationStateVersion) {
+      return void 0;
+    }
+    const version = await this.storage.getAuthorizationStateVersion();
+    return `v1:${this.authorDID}:${version.count}:${version.maxUpdatedAt}`;
+  }
   applyListPagination(nodes, options) {
     const offset = options?.offset ?? 0;
     const limit = options?.limit ?? nodes.length;
@@ -3372,8 +3413,16 @@ var DEFAULT_QUERY_VERIFICATION = {
   logFailures: true
 };
 var QUERY_TELEMETRY_FLUSH_THRESHOLD = 50;
+var COMPILED_QUERY_DIAGNOSTICS_MEMO_LIMIT = 512;
 var SQLITE_BIND_PARAMETER_BATCH_SIZE = 900;
 var SQLITE_HYDRATE_NODE_BATCH_SIZE = Math.floor(SQLITE_BIND_PARAMETER_BATCH_SIZE / 2);
+var SQL_HYDRATE_ARITY_BUCKETS = [1, 10, 50, 150, SQLITE_HYDRATE_NODE_BATCH_SIZE];
+var SQL_IN_ARITY_BUCKETS = [10, 50, 300, SQLITE_BIND_PARAMETER_BATCH_SIZE];
+function padToArityBucket(items, buckets) {
+  const size = buckets.find((bucket) => bucket >= items.length) ?? items.length;
+  if (size === items.length) return items;
+  return [...items, ...Array(size - items.length).fill(null)];
+}
 function getMaterializedQueryRefreshReason(input) {
   if (!input.cached) {
     return "missing";
@@ -3384,6 +3433,9 @@ function getMaterializedQueryRefreshReason(input) {
   if (input.cached.descriptor_hash !== input.descriptorHash) {
     return "descriptor-changed";
   }
+  if ((input.cached.auth_fingerprint ?? null) !== input.authFingerprint) {
+    return "authz-changed";
+  }
   if (input.cached.invalidated_at !== null) {
     return "invalidated";
   }
@@ -3407,19 +3459,42 @@ var SQLiteNodeStorageAdapter = class {
       ...options.queryVerification
     };
     this.queryDiagnostics = options.queryDiagnostics ?? false;
+    this.aggregatedHydration = options.aggregatedHydration ?? true;
+    this.scheduleMaintenance = options.scheduleMaintenance;
   }
   // Prepared statement cache for hot paths
   stmtCache = /* @__PURE__ */ new Map();
   adaptiveIndexing;
   queryVerification;
   queryDiagnostics;
+  /** Hydrate one row per node via json_group_object (0264 Wave 2 flag). */
+  aggregatedHydration;
+  /** Idle scheduler for maintenance work (adaptive index creation, 0264). */
+  scheduleMaintenance;
   pendingQueryTelemetry = /* @__PURE__ */ new Map();
   pendingQueryTelemetryHits = 0;
   adaptiveIndexBudgetColumnsReady = false;
   storageCapabilitiesPromise;
+  /**
+   * Plan diagnostics memoized per compiled SQL shape (the string EXPLAINed),
+   * shared across executions AND concurrent callers. Cleared when this adapter
+   * creates/drops an adaptive index, since that changes plans. Debug mode must
+   * not distort what it measures: per-execution EXPLAIN + index-inventory
+   * round-trips convoyed the single serial worker at boot.
+   */
+  compiledQueryDiagnosticsMemo = /* @__PURE__ */ new Map();
   spatialTablesState = "unknown";
   fullTextSearchTablesState = "unknown";
   writeQueue = Promise.resolve();
+  /**
+   * Read-authorization filter applied before persisting a materialized view's
+   * id list (exploration 0226). Wired by `NodeStore` when an auth evaluator is
+   * present; `undefined` means materialized views are computed unauthorized
+   * (the trusted single-user case).
+   */
+  nodeReadAuthorizer;
+  /** One-time guard: ensure the `auth_fingerprint` column exists on upgraded DBs. */
+  materializationColumnsReady = false;
   getSQLiteAdapter() {
     return this.db;
   }
@@ -3574,6 +3649,66 @@ var SQLiteNodeStorageAdapter = class {
     );
     return rows.map((row) => this.deserializeChange(row));
   }
+  /**
+   * Compact the local change log (exploration 0254 / F3): delete only
+   * *superseded* history so the OPFS file shrinks (fast cold open) and the
+   * outbound-resync slice shrinks (cheap first sync), without affecting reads,
+   * outbound sync, hash-chain chaining, or convergence with peers that never
+   * compacted.
+   *
+   * A row is deleted iff ALL of:
+   *  - `lamport_time < wsafe` — below the confirmed-durable floor, so the hub
+   *    holds it and it is not part of the unconfirmed outbound tail (K1);
+   *  - it is NOT a node's hash-chain tip — we keep every row at a node's
+   *    `MAX(lamport_time)` (the whole tie group), so `getLastChange()` still
+   *    returns a real tip and the next write's `parentHash`/hash/signature are
+   *    byte-identical to an uncompacted peer's (K2);
+   *  - it backs NO currently-winning LWW value — its `(node_id, lamport_time,
+   *    author)` is not the provenance of any live `node_properties` row (K3).
+   *
+   * K3 is the load-bearing safety net: because every live projection value keeps
+   * its backing row, the retained log still materialises to — and can re-push —
+   * the exact current state, so a stranded/rolled-back peer never loses live
+   * data. Reads are unaffected (they read the materialized `nodes`/
+   * `node_properties`, never the log). Only rows are deleted, never rewritten
+   * (the hash + signature are immutable and unforgeable). Runs chunked inside
+   * the write lane, yields between chunks, and never throws.
+   */
+  async pruneSupersededChanges(wsafe, options = {}) {
+    const chunk = Math.max(1, Math.floor(options.chunk ?? 5e3));
+    const maxRows = Math.max(0, Math.floor(options.maxRows ?? 25e4));
+    if (!Number.isFinite(wsafe) || wsafe <= 0 || maxRows === 0) return { deleted: 0 };
+    let deleted = 0;
+    for (; ; ) {
+      const remaining = maxRows - deleted;
+      const limit = Math.min(chunk, remaining);
+      if (limit <= 0) break;
+      const affected = await this.enqueueWrite(async () => {
+        const result = await this.db.run(
+          `DELETE FROM changes WHERE hash IN (
+             SELECT c.hash FROM changes c
+             WHERE c.lamport_time < ?
+               AND c.lamport_time < (
+                 SELECT MAX(t.lamport_time) FROM changes t WHERE t.node_id = c.node_id
+               )
+               AND NOT EXISTS (
+                 SELECT 1 FROM node_properties p
+                 WHERE p.node_id = c.node_id
+                   AND p.lamport_time = c.lamport_time
+                   AND p.updated_by = c.author
+               )
+             LIMIT ?
+           )`,
+          [wsafe, limit]
+        );
+        return result.changes ?? 0;
+      });
+      deleted += affected;
+      if (affected < limit) break;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    return { deleted };
+  }
   async getChangeByHash(hash) {
     const row = await this.db.queryOne(
       `SELECT hash, node_id, payload, lamport_time, 
@@ -3599,7 +3734,8 @@ var SQLiteNodeStorageAdapter = class {
     const changes = /* @__PURE__ */ new Map();
     if (uniqueIds.length === 0) return changes;
     for (const batch of chunkItems(uniqueIds, SQLITE_BIND_PARAMETER_BATCH_SIZE)) {
-      const placeholders = batch.map(() => "?").join(", ");
+      const padded = padToArityBucket(batch, SQL_IN_ARITY_BUCKETS);
+      const placeholders = padded.map(() => "?").join(", ");
       const rows = await this.db.query(
         `SELECT hash, node_id, payload, lamport_time,
                 lamport_peer as lamport_author, wall_time,
@@ -3613,7 +3749,7 @@ var SQLiteNodeStorageAdapter = class {
              ORDER BY c2.lamport_time DESC
              LIMIT 1
            )`,
-        batch
+        padded
       );
       rows.forEach((row) => {
         changes.set(row.node_id, this.deserializeChange(row));
@@ -3628,57 +3764,24 @@ var SQLiteNodeStorageAdapter = class {
   }
   // ─── Materialized State Operations ────────────────────────────────────────
   async getNode(id) {
-    const nodeRow = await this.db.queryOne(`SELECT * FROM nodes WHERE id = ?`, [id]);
-    if (!nodeRow) return null;
-    const propRows = await this.db.query(
-      `SELECT * FROM node_properties WHERE node_id = ?`,
-      [id]
-    );
-    const properties = {};
-    const timestamps = {};
-    let updatedBy = nodeRow.created_by;
-    for (const prop of propRows) {
-      properties[prop.property_key] = this.deserializeValue(prop.value);
-      timestamps[prop.property_key] = {
-        lamport: prop.lamport_time,
-        author: prop.updated_by,
-        wallTime: prop.updated_at
-      };
-      if (prop.updated_at >= nodeRow.updated_at) {
-        updatedBy = prop.updated_by;
-      }
-    }
-    return {
-      id: nodeRow.id,
-      schemaId: nodeRow.schema_id,
-      properties,
-      timestamps,
-      deleted: nodeRow.deleted_at !== null,
-      deletedAt: nodeRow.deleted_at ? { lamport: 0, author: "", wallTime: nodeRow.deleted_at } : void 0,
-      createdAt: nodeRow.created_at,
-      createdBy: nodeRow.created_by,
-      updatedAt: nodeRow.updated_at,
-      updatedBy
-    };
+    const nodes = await this.hydrateNodesByIds([id]);
+    return nodes[0] ?? null;
   }
   async getNodes(ids) {
     const uniqueIds = Array.from(new Set(ids));
     if (uniqueIds.length === 0) return [];
-    const nodes = [];
-    for (const batch of chunkItems(uniqueIds, SQLITE_HYDRATE_NODE_BATCH_SIZE)) {
-      nodes.push(...await this.hydrateNodesByIds(batch));
-    }
-    return nodes;
+    return this.hydrateNodesByIds(uniqueIds);
   }
   async getExistingNodeIds(ids) {
     const uniqueIds = Array.from(new Set(ids));
     if (uniqueIds.length === 0) return [];
     const existingIds = /* @__PURE__ */ new Set();
     for (const batch of chunkItems(uniqueIds, SQLITE_BIND_PARAMETER_BATCH_SIZE)) {
-      const placeholders = batch.map(() => "?").join(", ");
+      const padded = padToArityBucket(batch, SQL_IN_ARITY_BUCKETS);
+      const placeholders = padded.map(() => "?").join(", ");
       const rows = await this.db.query(
         `SELECT id FROM nodes WHERE id IN (${placeholders})`,
-        batch
+        padded
       );
       rows.forEach((row) => existingIds.add(row.id));
     }
@@ -3882,15 +3985,27 @@ var SQLiteNodeStorageAdapter = class {
       this.debugQueryPlan(descriptor, result2);
       return result2;
     }
-    const [queryDiagnostics, idQuery] = await Promise.all([
+    const [queryDiagnostics, mainQuery] = await Promise.all([
       this.isQueryDiagnosticsEnabled() ? this.collectCompiledQueryDiagnostics(compiled) : Promise.resolve({}),
-      timeQuery(this.db, compiled.sql, compiled.params)
+      compiled.fused ? timeQuery(this.db, compiled.fused.sql, compiled.fused.params) : timeQuery(this.db, compiled.sql, compiled.params)
     ]);
-    const idRows = idQuery.result;
-    const ids = idRows.map((row) => row.id);
-    const candidates = await this.hydrateNodesByIds(ids);
+    let candidates;
+    let candidateCount;
+    let fusedExactCount;
+    if (compiled.fused) {
+      const rows = mainQuery.result;
+      candidates = this.aggregatedHydration ? this.hydrateAggregatedRows(rows) : this.hydrateJoinedRows(rows);
+      candidateCount = candidates.length;
+      if (compiled.fused.includesExactCount && rows.length > 0) {
+        fusedExactCount = Number(rows[0].total_count ?? 0);
+      }
+    } else {
+      const ids = mainQuery.result.map((row) => row.id);
+      candidates = await this.hydrateNodesByIds(ids);
+      candidateCount = ids.length;
+    }
     const nodes = applyNodeQueryDescriptor(candidates, compiled.postFilterDescriptor);
-    const totalCount = compiled.sqlPagination ? descriptor.count === "exact" ? await this.countCompiledNodeQuery(descriptor, spatialPlan, fullTextSearchPlan) : void 0 : applyNodeQueryDescriptor(
+    const totalCount = compiled.sqlPagination ? descriptor.count === "exact" ? fusedExactCount ?? (candidateCount === 0 && (descriptor.offset ?? 0) === 0 ? 0 : await this.countCompiledNodeQuery(descriptor, spatialPlan, fullTextSearchPlan)) : void 0 : applyNodeQueryDescriptor(
       candidates,
       withoutNodeQueryPagination(compiled.postFilterDescriptor)
     ).length;
@@ -3903,14 +4018,14 @@ var SQLiteNodeStorageAdapter = class {
       totalCount,
       plan: {
         strategy: "storage-query",
-        candidateNodeCount: ids.length,
+        candidateNodeCount: candidateCount,
         hydratedNodeCount: candidates.length,
         returnedNodeCount: nodes.length,
         durationMs: Date.now() - start,
-        sql: compiled.sql,
-        params: compiled.params,
+        sql: compiled.fused ? compiled.fused.sql : compiled.sql,
+        params: compiled.fused ? compiled.fused.params : compiled.params,
         postFilterReason: compiled.postFilterReason,
-        candidateQueryDurationMs: idQuery.durationMs,
+        candidateQueryDurationMs: mainQuery.durationMs,
         ...candidateAccelerators.length > 0 ? {
           candidateAccelerators
         } : {},
@@ -3959,6 +4074,21 @@ var SQLiteNodeStorageAdapter = class {
     );
     return row ? parseInt(row.value, 10) || 0 : 0;
   }
+  /**
+   * The lowest confirmed-durable sync cursor across every node-change room
+   * (`MIN` over the persisted `nodeSync:hwm:*` marks), or `null` when no room has
+   * ever confirmed. This is the safe compaction floor (exploration 0254): the
+   * hub durably holds every change at or below it. Returns `null` — never 0 — so
+   * a workspace that has never synced is left untouched.
+   */
+  async getMinConfirmedSyncCursor() {
+    const row = await this.db.queryOne(
+      `SELECT MIN(CAST(value AS INTEGER)) AS min_value
+         FROM sync_state WHERE key LIKE 'nodeSync:hwm:%'`
+    );
+    const value = row?.min_value;
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+  }
   async setSyncCursor(room, lamport) {
     await this.enqueueWrite(async () => {
       await this.db.run(
@@ -3969,6 +4099,27 @@ var SQLiteNodeStorageAdapter = class {
       );
     });
   }
+  // ─── App State (generic K/V, FK-free) ─────────────────────────────────────
+  /** Namespace app-state keys so they can't collide with sync cursors. */
+  appStateKey(key) {
+    return `app:${key}`;
+  }
+  async getAppState(key) {
+    const row = await this.db.queryOne(
+      `SELECT value FROM sync_state WHERE key = ?`,
+      [this.appStateKey(key)]
+    );
+    return row ? row.value : null;
+  }
+  async setAppState(key, value) {
+    await this.enqueueWrite(async () => {
+      await this.db.run(
+        `INSERT INTO sync_state (key, value) VALUES (?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+        [this.appStateKey(key), value]
+      );
+    });
+  }
   // ─── Document Content (Yjs) ───────────────────────────────────────────────
   async getDocumentContent(nodeId) {
     const row = await this.db.queryOne(
@@ -4697,19 +4848,10 @@ var SQLiteNodeStorageAdapter = class {
     }
     return Array.from(nodeMap.values());
   }
-  async hydrateNodesByIds(ids) {
-    if (ids.length === 0) {
-      return [];
-    }
-    if (ids.length > SQLITE_HYDRATE_NODE_BATCH_SIZE) {
-      const nodes = [];
-      for (const batch of chunkItems(ids, SQLITE_HYDRATE_NODE_BATCH_SIZE)) {
-        nodes.push(...await this.hydrateNodesByIds(batch));
-      }
-      return nodes;
-    }
-    const values = ids.map(() => "(?, ?)").join(", ");
-    const params = ids.flatMap((id, ordinal) => [id, ordinal]);
+  buildHydrateChunkQuery(ids) {
+    const padded = padToArityBucket(ids, SQL_HYDRATE_ARITY_BUCKETS);
+    const values = padded.map(() => "(?, ?)").join(", ");
+    const params = padded.flatMap((id, ordinal) => [id, ordinal]);
     const sql = `
       WITH wanted(id, ordinal) AS (
         VALUES ${values}
@@ -4732,14 +4874,123 @@ var SQLiteNodeStorageAdapter = class {
       LEFT JOIN node_properties p ON p.node_id = n.id
       ORDER BY wanted.ordinal ASC, p.property_key ASC
     `;
-    const rows = await this.db.query(sql, params);
-    return this.hydrateJoinedRows(rows);
+    return { sql, params };
+  }
+  async hydrateNodesByIds(ids) {
+    if (ids.length === 0) {
+      return [];
+    }
+    const aggregated = this.aggregatedHydration;
+    const chunks = ids.length > SQLITE_HYDRATE_NODE_BATCH_SIZE ? chunkItems(ids, SQLITE_HYDRATE_NODE_BATCH_SIZE) : [ids];
+    const reads = chunks.map(
+      (chunk) => aggregated ? this.buildAggregatedHydrateChunkQuery(chunk) : this.buildHydrateChunkQuery(chunk)
+    );
+    const parse = (rows) => aggregated ? this.hydrateAggregatedRows(rows) : this.hydrateJoinedRows(rows);
+    if (reads.length > 1 && typeof this.db.queryBatch === "function") {
+      const results = await this.db.queryBatch(reads);
+      const nodes2 = [];
+      for (const rows of results) {
+        nodes2.push(...parse(rows));
+      }
+      return nodes2;
+    }
+    const nodes = [];
+    for (const read of reads) {
+      const rows = await this.db.query(read.sql, read.params);
+      nodes.push(...parse(rows));
+    }
+    return nodes;
+  }
+  /**
+   * Aggregated hydrate (exploration 0264, Wave 2): collapse the EAV rows to
+   * ONE row per node inside SQL via `json_group_object`, so the boundary
+   * ships N rows instead of N × properties. `value` is stored as JSON text
+   * in a BLOB — `json(CAST(… AS TEXT))` re-emits it as real JSON inside the
+   * aggregate (without the cast/wrap it would double-encode as a string).
+   */
+  buildAggregatedHydrateChunkQuery(ids) {
+    const padded = padToArityBucket(ids, SQL_HYDRATE_ARITY_BUCKETS);
+    const values = padded.map(() => "(?, ?)").join(", ");
+    const params = padded.flatMap((id, ordinal) => [id, ordinal]);
+    const sql = `
+      WITH wanted(id, ordinal) AS (
+        VALUES ${values}
+      )
+      SELECT
+        n.id,
+        n.schema_id,
+        n.created_at,
+        n.updated_at,
+        n.created_by,
+        n.deleted_at,
+        wanted.ordinal,
+        json_group_object(p.property_key, json(CAST(p.value AS TEXT)))
+          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)
+        ) FILTER (WHERE p.property_key IS NOT NULL) AS meta_json
+      FROM wanted
+      JOIN nodes n ON n.id = wanted.id
+      LEFT JOIN node_properties p ON p.node_id = n.id
+      GROUP BY n.id
+      ORDER BY wanted.ordinal ASC
+    `;
+    return { sql, params };
+  }
+  /** Parse one-row-per-node aggregated hydrate results into NodeStates. */
+  hydrateAggregatedRows(rows) {
+    const nodes = [];
+    for (const row of rows) {
+      const properties = row.props_json ? JSON.parse(row.props_json) : {};
+      const meta = row.meta_json ? JSON.parse(row.meta_json) : {};
+      const timestamps = {};
+      let updatedBy = row.created_by;
+      for (const [key, entry] of Object.entries(meta)) {
+        timestamps[key] = {
+          lamport: entry.l ?? 0,
+          author: entry.b ?? "",
+          wallTime: entry.w ?? 0
+        };
+        if ((entry.w ?? 0) >= row.updated_at) {
+          updatedBy = entry.b ?? row.created_by;
+        }
+      }
+      nodes.push({
+        id: row.id,
+        schemaId: row.schema_id,
+        properties,
+        timestamps,
+        deleted: row.deleted_at !== null,
+        deletedAt: row.deleted_at ? { lamport: 0, author: "", wallTime: row.deleted_at } : void 0,
+        createdAt: row.created_at,
+        createdBy: row.created_by,
+        updatedAt: row.updated_at,
+        updatedBy
+      });
+    }
+    return nodes;
   }
+  /**
+   * Read (or refresh) a materialized view.
+   *
+   * A materialized view is a purely LOCAL, DERIVED cache: an ordered list of
+   * node ids (membership + order) plus bookkeeping. It is NEVER part of the
+   * change log and is NEVER synced — peers each derive their own. It therefore
+   * carries no authority and can be rebuilt or dropped at any time (a wiped
+   * cache only costs a recompute, never data). Content is re-hydrated from the
+   * live `nodes`/`node_properties` tables on every read, so the cache exposes
+   * nothing the underlying tables don't already, and a write to the schema
+   * (`invalidated_at`) or a grant change (`auth_fingerprint`) forces a
+   * re-materialization. See exploration 0226.
+   */
   async queryMaterializedView(descriptor, start) {
     const materializedView = descriptor.materializedView;
     if (!materializedView) {
       throw new Error("Materialized view query requires descriptor.materializedView");
     }
+    await this.ensureMaterializationColumns();
+    const authFingerprint = descriptor.authFingerprint ?? null;
     const baseDescriptor = withoutNodeQueryMaterializedView(withoutNodeQueryPagination(descriptor));
     const descriptorJson = this.stringifyStable(baseDescriptor);
     const descriptorHash = this.hashScalarValue(descriptorJson);
@@ -4748,10 +4999,11 @@ var SQLiteNodeStorageAdapter = class {
     const refreshReason = getMaterializedQueryRefreshReason({
       cached,
       descriptorHash,
+      authFingerprint,
       cacheExpired,
       forceRefresh: materializedView.forceRefresh ?? false
     });
-    const canUseCache = cached !== null && cached.descriptor_hash === descriptorHash && cached.invalidated_at === null && !cacheExpired && !materializedView.forceRefresh;
+    const canUseCache = cached !== null && cached.descriptor_hash === descriptorHash && (cached.auth_fingerprint ?? null) === authFingerprint && cached.invalidated_at === null && !cacheExpired && !materializedView.forceRefresh;
     const readPlan = canUseCache ? {
       viewId: materializedView.viewId,
       descriptorHash,
@@ -4764,6 +5016,7 @@ var SQLiteNodeStorageAdapter = class {
       descriptor: baseDescriptor,
       descriptorHash,
       descriptorJson,
+      authFingerprint,
       refreshReason: refreshReason ?? "missing",
       invalidatedAt: cached?.invalidated_at ?? null
     });
@@ -4780,14 +5033,63 @@ var SQLiteNodeStorageAdapter = class {
          descriptor_json,
          generated_at,
          invalidated_at,
-         row_count
+         row_count,
+         auth_fingerprint
        FROM node_query_materializations
        WHERE view_id = ?`,
       [viewId]
     );
   }
+  /**
+   * Ensure the `auth_fingerprint` column exists. Fresh databases get it from
+   * the DDL; databases upgraded in place (the runtime applies the full DDL with
+   * `CREATE TABLE IF NOT EXISTS`, which cannot add a column) need this guard.
+   * Idempotent and memoized (exploration 0226).
+   */
+  async ensureMaterializationColumns() {
+    if (this.materializationColumnsReady) return;
+    try {
+      const columns = await this.db.query(
+        `PRAGMA table_info(node_query_materializations)`
+      );
+      const hasColumn = columns.some((column) => column.name === "auth_fingerprint");
+      if (!hasColumn) {
+        await this.db.run(
+          "ALTER TABLE node_query_materializations ADD COLUMN auth_fingerprint TEXT"
+        );
+      }
+    } catch {
+    }
+    this.materializationColumnsReady = true;
+  }
+  setNodeReadAuthorizer(authorizer) {
+    this.nodeReadAuthorizer = authorizer;
+  }
+  /**
+   * Reload-stable version of the authorization-relevant control-plane state:
+   * grants (`Grant` schema) and per-subject `/sys/authz/` resources. Ordinary
+   * data writes do not touch these, so a database's materialized views survive
+   * reloads and edits, but any grant change shifts `count`/`maxUpdatedAt` and
+   * forces an `'authz-changed'` refresh (exploration 0226).
+   */
+  async getAuthorizationStateVersion() {
+    const grantIri = SYSTEM_SCHEMA_BASE_IRIS.Grant;
+    const row = await this.db.queryOne(
+      `SELECT COUNT(*) AS count, COALESCE(MAX(updated_at), 0) AS max_updated_at
+       FROM nodes
+       WHERE schema_id = ?
+          OR schema_id LIKE ?
+          OR id LIKE 'xnet://%/sys/authz/%'`,
+      [grantIri, `${grantIri}@%`]
+    );
+    return {
+      count: row?.count ?? 0,
+      maxUpdatedAt: row?.max_updated_at ?? 0
+    };
+  }
   async refreshMaterializedView(input) {
     const refreshed = await this.queryNodes(input.descriptor);
+    const authorizedNodes = this.nodeReadAuthorizer ? await this.nodeReadAuthorizer(refreshed.nodes) : refreshed.nodes;
     const generatedAt = Date.now();
     await this.enqueueWrite(async () => {
       await this.db.beginTransaction();
@@ -4804,26 +5106,29 @@ var SQLiteNodeStorageAdapter = class {
               descriptor_json,
               generated_at,
               invalidated_at,
-              row_count
+              row_count,
+              auth_fingerprint
             )
-           VALUES (?, ?, ?, ?, ?, NULL, ?)
+           VALUES (?, ?, ?, ?, ?, NULL, ?, ?)
            ON CONFLICT(view_id) DO UPDATE SET
              descriptor_hash = excluded.descriptor_hash,
              schema_id = excluded.schema_id,
              descriptor_json = excluded.descriptor_json,
              generated_at = excluded.generated_at,
              invalidated_at = NULL,
-             row_count = excluded.row_count`,
+             row_count = excluded.row_count,
+             auth_fingerprint = excluded.auth_fingerprint`,
           [
             input.viewId,
             input.descriptorHash,
             input.descriptor.schemaId,
             input.descriptorJson,
             generatedAt,
-            refreshed.nodes.length
+            authorizedNodes.length,
+            input.authFingerprint
           ]
         );
-        for (const [ordinal, node] of refreshed.nodes.entries()) {
+        for (const [ordinal, node] of authorizedNodes.entries()) {
           await this.db.run(
             `INSERT INTO node_query_materialized_ids (view_id, ordinal, node_id)
              VALUES (?, ?, ?)`,
@@ -4841,7 +5146,7 @@ var SQLiteNodeStorageAdapter = class {
       descriptorHash: input.descriptorHash,
       generatedAt,
       invalidatedAt: input.invalidatedAt,
-      rowCount: refreshed.nodes.length,
+      rowCount: authorizedNodes.length,
       cacheHit: false,
       refreshReason: input.refreshReason
     };
@@ -5359,6 +5664,23 @@ CREATE INDEX IF NOT EXISTS idx_node_spatial_ids_schema
     if (!stats || !this.shouldCreateAdaptiveIndexes(stats)) {
       return { descriptorHash, adaptiveIndexNames: [] };
     }
+    if (this.scheduleMaintenance) {
+      const input = {
+        descriptorHash,
+        schemaId: descriptor.schemaId,
+        hints: adaptiveIndexHints,
+        now
+      };
+      this.scheduleMaintenance(
+        () => this.ensureAdaptiveIndexes(input).then(
+          () => void 0,
+          (err) => {
+            console.warn("[SQLiteNodeStorageAdapter] deferred adaptive index skipped:", err);
+          }
+        )
+      );
+      return { descriptorHash, adaptiveIndexNames: [] };
+    }
     const adaptiveIndexNames = await this.ensureAdaptiveIndexes({
       descriptorHash,
       schemaId: descriptor.schemaId,
@@ -5428,7 +5750,34 @@ CREATE INDEX IF NOT EXISTS idx_node_spatial_ids_schema
   isQueryDiagnosticsEnabled() {
     return this.queryDiagnostics || this.isQueryDebugEnabled();
   }
-  async collectCompiledQueryDiagnostics(compiled) {
+  /**
+   * Throttled: one collection per unique compiled SQL shape per session.
+   * EXPLAIN plans depend on the statement, not the bound values, so keyset
+   * pages of the same query share one entry. Concurrent callers share the
+   * in-flight promise; failed collections are not memoized.
+   */
+  collectCompiledQueryDiagnostics(compiled) {
+    const memoKey = compiled.sql;
+    const memoized = this.compiledQueryDiagnosticsMemo.get(memoKey);
+    if (memoized) {
+      return memoized;
+    }
+    const pending = this.computeCompiledQueryDiagnostics(compiled).then((diagnostics) => {
+      if (diagnostics.diagnosticsError) {
+        this.compiledQueryDiagnosticsMemo.delete(memoKey);
+      }
+      return diagnostics;
+    });
+    if (this.compiledQueryDiagnosticsMemo.size >= COMPILED_QUERY_DIAGNOSTICS_MEMO_LIMIT) {
+      const oldest = this.compiledQueryDiagnosticsMemo.keys().next().value;
+      if (oldest !== void 0) {
+        this.compiledQueryDiagnosticsMemo.delete(oldest);
+      }
+    }
+    this.compiledQueryDiagnosticsMemo.set(memoKey, pending);
+    return pending;
+  }
+  async computeCompiledQueryDiagnostics(compiled) {
     try {
       const [analysis, indexes, storageCapabilities] = await Promise.all([
         analyzeQuery(this.db, compiled.sql, compiled.params),
@@ -5484,6 +5833,9 @@ CREATE INDEX IF NOT EXISTS idx_node_spatial_ids_schema
     if (!this.queryVerification.enabled) {
       return { strategy: "skipped", reason: "disabled" };
     }
+    if (this.nodeReadAuthorizer) {
+      return { strategy: "skipped", reason: "authorized-materialization" };
+    }
     const candidateScopeCount = descriptor.nodeId ? 1 : await this.countNodes({
       schemaId: descriptor.schemaId,
       includeDeleted: descriptor.includeDeleted
@@ -5649,6 +6001,7 @@ CREATE INDEX IF NOT EXISTS idx_node_spatial_ids_schema
     if (createdIndex) {
       await runAnalyze(this.db, "node_property_scalars");
       await this.db.exec("PRAGMA optimize");
+      this.compiledQueryDiagnosticsMemo.clear();
     }
     return touchedIndexNames;
   }
@@ -5797,6 +6150,7 @@ CREATE INDEX IF NOT EXISTS idx_node_spatial_ids_schema
   async dropAdaptiveIndex(indexName, reason) {
     await this.db.exec(`DROP INDEX IF EXISTS ${this.quoteSqlIdentifier(indexName)}`);
     await this.db.run("DELETE FROM query_index_candidates WHERE index_name = ?", [indexName]);
+    this.compiledQueryDiagnosticsMemo.clear();
     this.debugAdaptiveIndex("drop", { indexName, reason });
   }
   debugAdaptiveIndex(action, details) {
@@ -5880,17 +6234,37 @@ WHERE schema_id = ${this.quoteSqlLiteral(schemaId)}
     const hasPropertySort = Object.keys(descriptor.orderBy ?? {}).some(
       (key) => key !== "createdAt" && key !== "updatedAt"
     );
+    const propertySort = this.resolvePropertySortPushdown(descriptor, hasPropertySort);
     const hasSqlCandidateBenefit = scalarWhere.length > 0 || spatialPlan !== null || fullTextSearchPlan !== null || !descriptor.spatial || this.hasOnlySystemOrdering(descriptor.orderBy);
-    if (!hasSqlCandidateBenefit) {
+    if (!hasSqlCandidateBenefit && !propertySort) {
       return null;
     }
     return this.compileSqlQuery(descriptor, {
       whereEntries: scalarWhere,
-      canUseSqlPagination: !hasPropertySort && !descriptor.spatial && !descriptor.search,
+      canUseSqlPagination: (!hasPropertySort || propertySort !== null) && !descriptor.spatial && !descriptor.search,
       spatialPlan,
-      fullTextSearchPlan
+      fullTextSearchPlan,
+      propertySort
     });
   }
+  /**
+   * A custom-property sort can push down when it is the descriptor's ONLY
+   * order key and no cursor/spatial/search accelerator is in play. Gated on
+   * the adaptive-indexing flag: the typed partial indexes on
+   * `node_property_scalars` make the join+order cheap, and the flag keeps
+   * the behavioural change opt-in while it soaks (exploration 0264).
+   */
+  resolvePropertySortPushdown(descriptor, hasPropertySort) {
+    if (!hasPropertySort || !this.adaptiveIndexing.enabled) return null;
+    if (descriptor.spatial || descriptor.search || descriptor.after !== void 0) return null;
+    const entries = Object.entries(descriptor.orderBy ?? {}).filter(
+      (entry) => entry[1] === "asc" || entry[1] === "desc"
+    );
+    if (entries.length !== 1) return null;
+    const [key, direction] = entries[0];
+    if (key === "createdAt" || key === "updatedAt") return null;
+    return { key, direction };
+  }
   compileSqlQuery(descriptor, options) {
     const joins = [];
     const where = ["n.schema_id = ?"];
@@ -5945,7 +6319,17 @@ WHERE schema_id = ${this.quoteSqlLiteral(schemaId)}
         options.spatialPlan.bounds.maxY
       );
     }
-    const orderBy = this.buildSqlOrderBy(descriptor.orderBy);
+    if (options.propertySort) {
+      const schemaId = this.quoteSqlLiteral(descriptor.schemaId);
+      const propertyKey = this.quoteSqlLiteral(options.propertySort.key);
+      joins.push(
+        `LEFT JOIN node_property_scalars sortp
+          ON sortp.node_id = n.id
+         AND sortp.schema_id = ${schemaId}
+         AND sortp.property_key = ${propertyKey}`
+      );
+    }
+    const orderBy = options.propertySort ? this.buildPropertySortOrderBy(options.propertySort.direction) : this.buildSqlOrderBy(descriptor.orderBy);
     const useSqlPagination = options.canUseSqlPagination && descriptor.after === void 0 && (descriptor.limit !== void 0 || (descriptor.offset ?? 0) > 0);
     let sql = `
       SELECT n.id
@@ -5954,13 +6338,59 @@ WHERE schema_id = ${this.quoteSqlLiteral(schemaId)}
       WHERE ${where.join(" AND ")}
       ORDER BY ${orderBy}
     `;
+    let fused;
     if (useSqlPagination) {
       sql += "\nLIMIT ? OFFSET ?";
       whereParams.push(descriptor.limit ?? -1, descriptor.offset ?? 0);
+      const includesExactCount = descriptor.count === "exact";
+      const countColumn = includesExactCount ? ",\n          COUNT(*) OVER () AS total_count" : "";
+      const countSelect = includesExactCount ? "c.total_count," : "";
+      const candidatesCte = `
+      WITH candidates AS (
+        SELECT
+          n.id, n.schema_id, n.created_at, n.updated_at, n.created_by, n.deleted_at,
+          ROW_NUMBER() OVER (ORDER BY ${orderBy}) AS ordinal${countColumn}
+        FROM nodes n
+        ${joins.join("\n")}
+        WHERE ${where.join(" AND ")}
+        ORDER BY ${orderBy}
+        LIMIT ? OFFSET ?
+      )`;
+      const fusedSql = this.aggregatedHydration ? `${candidatesCte}
+      SELECT
+        c.id, c.schema_id, c.created_at, c.updated_at, c.created_by, c.deleted_at,
+        ${countSelect}
+        c.ordinal,
+        json_group_object(p.property_key, json(CAST(p.value AS TEXT)))
+          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)
+        ) FILTER (WHERE p.property_key IS NOT NULL) AS meta_json
+      FROM candidates c
+      LEFT JOIN node_properties p ON p.node_id = c.id
+      GROUP BY c.id
+      ORDER BY c.ordinal ASC
+    ` : `${candidatesCte}
+      SELECT
+        c.id, c.schema_id, c.created_at, c.updated_at, c.created_by, c.deleted_at,
+        ${countSelect}
+        p.property_key, p.value, p.lamport_time, p.updated_by, p.updated_at AS prop_updated_at,
+        c.ordinal
+      FROM candidates c
+      LEFT JOIN node_properties p ON p.node_id = c.id
+      ORDER BY c.ordinal ASC, p.property_key ASC
+    `;
+      fused = {
+        sql: fusedSql,
+        params: [...whereParams],
+        includesExactCount
+      };
     }
     return {
       sql,
       params: whereParams,
+      fused,
       postFilterDescriptor: useSqlPagination ? withoutNodeQueryPagination(descriptor) : descriptor,
       postFilterReason: this.getCompiledPostFilterReason({
         useSqlPagination,
@@ -6009,6 +6439,18 @@ WHERE schema_id = ${this.quoteSqlLiteral(schemaId)}
         return;
     }
   }
+  /**
+   * ORDER BY for a pushed-down custom-property sort (0264). Mirrors the JS
+   * comparator in `applyNodeQueryDescriptor`: missing properties sort last
+   * ascending / first descending; typed value columns carry the order (for a
+   * homogeneous property exactly one is non-NULL). `n.id` breaks ties so the
+   * page boundary is a total order.
+   */
+  buildPropertySortOrderBy(direction) {
+    const dir = direction.toUpperCase();
+    const nullsDir = direction === "asc" ? "ASC" : "DESC";
+    return `(sortp.node_id IS NULL) ${nullsDir}, sortp.value_number ${dir}, sortp.value_boolean ${dir}, sortp.value_text ${dir}, n.id ASC`;
+  }
   buildSqlOrderBy(orderBy) {
     const entries = Object.entries(orderBy ?? {}).filter(
       (entry) => entry[1] === "asc" || entry[1] === "desc"