querysub 0.691.0 → 0.693.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "querysub",
-  "version": "0.691.0",
+  "version": "0.693.0",
   "main": "index.js",
   "license": "MIT",
   "note1": "note on node-forge fork, see https://github.com/digitalbazaar/forge/issues/744 for details",

package/src/2-proxy/PathValueProxyWatcher.ts

@@ -13,7 +13,7 @@ import { ActionsHistory } from "../diagnostics/ActionsHistory";
 import { registerResource } from "../diagnostics/trackResources";
 import { ClientWatcher, WatchSpecData, clientWatcher } from "../1-path-client/pathValueClientWatcher";
 import { createPathValueProxy, getPathFromProxy, getProxyPath, getProxyPathAndWatch, isValueProxy, isValueProxy2 } from "./pathValueProxy";
-import { authorityStorage, compareTime, ReadLock, epochTime, getNextTime, MAX_ACCEPTED_CHANGE_AGE, PathValue, Time, getCreatorId, debugTime } from "../0-path-value-core/pathValueCore";
+import { authorityStorage, compareTime, ReadLock, epochTime, getNextTime, MAX_ACCEPTED_CHANGE_AGE, PathValue, Time, getCreatorId, debugTime, MAX_CHANGE_AGE } from "../0-path-value-core/pathValueCore";
 import { runCodeWithDatabase, rawSchema } from "./pathDatabaseProxyBase";
 import debugbreak from "debugbreak";
 import { pathValueCommitter } from "../0-path-value-core/PathValueController";
@@ -69,6 +69,7 @@ export function runWithPathValueReadSource<T>(source: PathValueReadSource, code:
 }
 
 let nextSeqNum = 1;
+let nextEvaluationId = 1;
 let nextOrderSeqNum = 1;
 
 export interface WatcherOptions<Result> {
@@ -328,6 +329,13 @@ export type SyncWatcher = {
     // Runs after any trigger happens (usually multiple triggers are required for a commit)
     onAfterTriggered: (() => void)[];
 
+    // A new id every run, so evaluation-scoped state (callLevelCache.ts) can detect it is stale.
+    evaluationId: number;
+    // Reset every time the function is run, like onInnerDisposed. Observe the evaluation's gets / getKeys / sets — they can't change them.
+    evaluationGetCallbacks: ((pathStr: string) => void)[];
+    evaluationGetKeysCallbacks: ((pathStr: string) => void)[];
+    evaluationSetCallbacks: ((pathStr: string) => void)[];
+
     // Not great, but... sometimes we just want to trigger the function
     explicitlyTrigger: (changes?: WatchSpecData) => void;
 
@@ -573,7 +581,8 @@ export class PathValueProxyWatcher {
         }
     };
 
-    public getCallbackPathValue = (pathStr: string, syncParentKeys?: "parentKeys"): PathValue | undefined => {
+    // TEMPORARY measure, remove once the catalog import's slowness is found.
+    public getCallbackPathValue = measureWrap((pathStr: string, syncParentKeys?: "parentKeys"): PathValue | undefined => {
         const watcher = this.runningWatcher;
         if (!watcher) {
             debugger;
@@ -587,13 +596,13 @@ export class PathValueProxyWatcher {
         if (watcher.permissionsChecker) {
             if (!watcher.permissionsChecker.checkPermissions(pathStr).allowed) {
                 if (
-                    !watcher.hasAnyUnsyncedAccesses()
-                    && currentReadSource.DEBUG_hasAnyValues(pathStr)
                     // HACK: Don't show warnings for some framework paths, because they are filling up the console logs
                     //  and don't really matter. We could just not request them, but at depth 3 is valid,
                     //  so we kind of have to request that. And at depth 2, it would require special case code,
                     //  in a bunch of annoying places.
-                    && (getPathIndex(pathStr, 1) !== "PathFunctionRunner" || getPathDepth(pathStr) > 3)
+                    (getPathIndex(pathStr, 1) !== "PathFunctionRunner" || getPathDepth(pathStr) > 3)
+                    && currentReadSource.DEBUG_hasAnyValues(pathStr)
+                    && !watcher.hasAnyUnsyncedAccesses()
                 ) {
                     console.warn(`Denied read access to path "${pathStr}"`);
                     // console.warn(`${new Date().toLocaleTimeString()} Denied read access to path "${pathStr}"`);
@@ -662,8 +671,12 @@ export class PathValueProxyWatcher {
         }
 
         return pathValue;
-    };
-    public getCallback = (pathStr: string, syncParentKeys?: "parentKeys", readTransparent?: "readTransparent"): { value: unknown } | undefined => {
+    }, "PathValueProxyWatcher|getCallbackPathValue");
+    // TEMPORARY measure, remove once the catalog import's slowness is found.
+    public getCallback = measureWrap((pathStr: string, syncParentKeys?: "parentKeys", readTransparent?: "readTransparent"): { value: unknown } | undefined => {
+        if (this.runningWatcher && this.runningWatcher.evaluationGetCallbacks.length > 0) {
+            for (let callback of this.runningWatcher.evaluationGetCallbacks) callback(pathStr);
+        }
         if (PathValueProxyWatcher.BREAK_ON_READS.size > 0 && (proxyWatcher.isAllSynced({ checkCommitAllRunsFlag: true }) || this)) {
             // NOTE: We can't do a recursive match, as the parent paths include the 
             //  root, which is constantly read, but not relevant.
@@ -739,7 +752,7 @@ export class PathValueProxyWatcher {
             }
             return { value: readValue };
         }
-    };
+    }, "PathValueProxyWatcher|getCallback");
 
     // We exclude undefined, BUT, we include "null", etc.
     //  - This differs from javascript, but... due to how deletions work, we can't/don't differentiate between
@@ -749,7 +762,11 @@ export class PathValueProxyWatcher {
         return value?.value !== undefined;
     };
 
-    public setCallback = (pathStr: string, value: unknown, inRecursion = false, allowSpecial = false): void => {
+    // TEMPORARY measure, remove once the catalog import's slowness is found.
+    public setCallback = measureWrap((pathStr: string, value: unknown, inRecursion = false, allowSpecial = false): void => {
+        if (this.runningWatcher && this.runningWatcher.evaluationSetCallbacks.length > 0) {
+            for (let callback of this.runningWatcher.evaluationSetCallbacks) callback(pathStr);
+        }
         if (PathValueProxyWatcher.BREAK_ON_WRITES.size > 0 && proxyWatcher.isAllSynced({ checkCommitAllRunsFlag: true })) {
             if (isRecursiveMatch(PathValueProxyWatcher.BREAK_ON_WRITES, pathStr)) {
                 let unwatch = () => removeMatches(PathValueProxyWatcher.BREAK_ON_WRITES, pathStr);
@@ -922,9 +939,13 @@ export class PathValueProxyWatcher {
             }
             watcher.pendingWrites.set(pathStr, value);
         }
-    };
+    }, "PathValueProxyWatcher|setCallback");
     /** Syncs keys AND values (as we won't return a key for a value that is undefined). */
-    public getKeys = (pathStr: string): string[] => {
+    // TEMPORARY measure, remove once the catalog import's slowness is found.
+    public getKeys = measureWrap((pathStr: string): string[] => {
+        if (this.runningWatcher && this.runningWatcher.evaluationGetKeysCallbacks.length > 0) {
+            for (let callback of this.runningWatcher.evaluationGetKeysCallbacks) callback(pathStr);
+        }
         if (getPathDepth(pathStr) < MODULE_INDEX) {
             throw new Error(`Cannot call getKeys on path "${pathStr}" because it is too shallow. Must be at least ${MODULE_INDEX} levels deep.`);
         }
@@ -1005,7 +1026,7 @@ export class PathValueProxyWatcher {
         keysArray.sort();
 
         return keysArray;
-    };
+    }, "PathValueProxyWatcher|getKeys");
 
     private getSymbol = (pathStr: string, symbol: symbol): { value: unknown } | undefined => {
         if (symbol === Symbol.toPrimitive) return {
@@ -1054,6 +1075,39 @@ export class PathValueProxyWatcher {
 
     private runningWatcher: SyncWatcher | undefined;
 
+    /** Identifies the current watcher evaluation, or undefined outside of one. A new evaluation always gets a new id, so holding an id is how a caller detects that its evaluation-scoped state is stale. */
+    public getEvaluationId(): number | undefined {
+        if (!this.runningWatcher) return undefined;
+        return this.runningWatcher.evaluationId;
+    }
+    public onEvaluationGet(callback: (pathStr: string) => void): () => void {
+        const watcher = this.runningWatcher;
+        if (!watcher) throw new Error(`onEvaluationGet requires a running watcher evaluation`);
+        watcher.evaluationGetCallbacks.push(callback);
+        return () => {
+            let index = watcher.evaluationGetCallbacks.indexOf(callback);
+            if (index >= 0) watcher.evaluationGetCallbacks.splice(index, 1);
+        };
+    }
+    public onEvaluationGetKeys(callback: (pathStr: string) => void): () => void {
+        const watcher = this.runningWatcher;
+        if (!watcher) throw new Error(`onEvaluationGetKeys requires a running watcher evaluation`);
+        watcher.evaluationGetKeysCallbacks.push(callback);
+        return () => {
+            let index = watcher.evaluationGetKeysCallbacks.indexOf(callback);
+            if (index >= 0) watcher.evaluationGetKeysCallbacks.splice(index, 1);
+        };
+    }
+    public onEvaluationSet(callback: (pathStr: string) => void): () => void {
+        const watcher = this.runningWatcher;
+        if (!watcher) throw new Error(`onEvaluationSet requires a running watcher evaluation`);
+        watcher.evaluationSetCallbacks.push(callback);
+        return () => {
+            let index = watcher.evaluationSetCallbacks.indexOf(callback);
+            if (index >= 0) watcher.evaluationSetCallbacks.splice(index, 1);
+        };
+    }
+
     // NOTE: We can't support promises until we are able to run the function on another
     //  thread (at which point we can ensure there is no parallel function running).
     public createWatcher<Result = void>(
@@ -1115,9 +1169,8 @@ export class PathValueProxyWatcher {
 
         const self = this;
         if (options.runAtTime) {
-            // 80% of our real max range, so calls with a runAtTime close to our limit have a bit of breathing room to run
-            let runLeeway = MAX_ACCEPTED_CHANGE_AGE * 0.8;
-            let runCutoffTime = Date.now() - runLeeway;
+            // Fail early because if it's slow, it could easily take 10 or 15 minutes before it fully synchronizes. And there's no point in waiting all that time, re-evaluating so many times, and then just failing after all that when we knew we were going fail anyways.
+            let runCutoffTime = Date.now() - MAX_CHANGE_AGE;
             if (options.runAtTime && options.runAtTime.time < runCutoffTime) {
                 let message = `MAX_CHANGE_AGE_EXCEEDED! Cannot run watcher ${options.debugName} at time ${options.runAtTime.time} because it is older than the cutOff time of ${runCutoffTime}. Writing this far in the past would break things, and might be rejected by other authorities due to being too old.`;
                 console.error(red(message));
@@ -1143,6 +1196,10 @@ export class PathValueProxyWatcher {
             disposed: false,
             onInnerDisposed: [],
             onAfterTriggered: [],
+            evaluationId: 0,
+            evaluationGetCallbacks: [],
+            evaluationGetKeysCallbacks: [],
+            evaluationSetCallbacks: [],
             explicitlyTrigger: () => { },
             hasAnyUnsyncedAccesses: () => false,
             currentReadTime: options.runAtTime,
@@ -1297,6 +1354,10 @@ export class PathValueProxyWatcher {
             // IMPORTANT! Reset onInnerDisposed, so onCommitFinished doesn't result in a callback
             //  per time we wan the watcher!
             watcher.onInnerDisposed = [];
+            watcher.evaluationId = nextEvaluationId++;
+            watcher.evaluationGetCallbacks = [];
+            watcher.evaluationGetKeysCallbacks = [];
+            watcher.evaluationSetCallbacks = [];
             watcher.specialPromiseUnsynced = false;
 
             // NOTE: If runAtTime is undefined, the writeTime will be undefined, causing us to read the latest data.
@@ -1331,6 +1392,16 @@ export class PathValueProxyWatcher {
 
             let result: { result: Result } | { error: string };
             try {
+                // Mirrors the same check at watcher creation, because a call can also die MID-sync: every rerun waits for more data while the write time stays fixed at runAtTime, so once that is too old the eventual commit can only ever be rejected (PathValueCommitter's MAX_CHANGE_AGE check). Failing here, before any reads (so nothing registers as unsynced and the error actually reports instead of the watcher waiting again), saves the entire remaining sync — potentially minutes of work that would end in that same error anyway.
+                if (watcher.options.runAtTime && watcher.options.canWrite) {
+                    let runLeeway = MAX_ACCEPTED_CHANGE_AGE * 0.8;
+                    let runCutoffTime = Date.now() - runLeeway;
+                    if (watcher.options.runAtTime.time < runCutoffTime) {
+                        let message = `MAX_CHANGE_AGE_EXCEEDED! Cannot continue running watcher ${watcher.debugName} at time ${watcher.options.runAtTime.time}, it is older than the cutoff time of ${runCutoffTime}. Its writes could never be committed (they would be rejected as too far in the past), so failing now instead of after syncing even more.`;
+                        console.error(red(message));
+                        throw new Error(message);
+                    }
+                }
                 let rawResult: Result;
                 const handling = watcher.options.nestedCalls;
                 let curFunction = baseFunction;

package/src/2-proxy/TransactionDelayer.ts

@@ -1,4 +1,5 @@
 import { delay } from "socket-function/src/batching";
+import { measureWrap } from "socket-function/src/profiling/measure";
 import { PathValue, hashPathForTransaction, compareTime, Time, authorityStorage, epochTime, createMissingEpochValue, MISSING_TRANSACTION_PART_TIMEOUT, debugPathValue } from "../0-path-value-core/pathValueCore";
 import { SyncWatcher, proxyWatcher } from "./PathValueProxyWatcher";
 import { isDefined } from "../misc";
@@ -66,33 +67,27 @@ export function isMissingTransactionPart(pathValues: PathValue[], timeoutCheck?:
     return newestWaitTime;
 }
 
-export function getAllPendingPathValueReads(watcher = proxyWatcher.getTriggeredWatcher()) {
+function getPendingPathValueReadsNewerThan(watcher: SyncWatcher, oldestTime: number) {
     let values: PathValue[] = [];
     for (let map of watcher.pendingAccesses.values()) {
         for (let pathValue of map.values()) {
+            if (pathValue.pathValue.time.time < oldestTime) continue;
             values.push(pathValue.pathValue);
         }
     }
-    // NOTE: These can't contribute the transaction paths, but they do contribute their path and their time, which will cause other transaction paths to know that they are invalid. 
-    let allEpochPaths = new Set<string>();
-    for (let paths of watcher.pendingEpochAccesses.values()) {
-        for (let path of paths) {
-            allEpochPaths.add(path);
-        }
-    }
-    for (let path of allEpochPaths) {
-        values.push(createMissingEpochValue(path));
-    }
     return values;
 }
 
 
-export function waitIfReceivedIncompleteTransaction(watcher: SyncWatcher) {
+export const waitIfReceivedIncompleteTransaction = measureWrap(function waitIfReceivedIncompleteTransaction(watcher: SyncWatcher) {
     // We don't want to register a whole bunch of duplicate promises. So if somebody's waiting, there's no need to even do our check. 
     if (watcher.specialPromiseUnsynced) return;
 
     let readTime = watcher.currentReadTime;
-    let pendingValuePaths = getAllPendingPathValueReads(watcher);
+    // Transactions have the same time, so we don't have to worry about filtering out part of a transaction, not the other. And if the transaction is too old, we're not going to care if there are missing parts. So we can just ignore anything that's older than this.
+    let oldestTime = Date.now() - MISSING_TRANSACTION_PART_TIMEOUT;
+    let pendingValuePaths = getPendingPathValueReadsNewerThan(watcher, oldestTime);
+
     const newestTime = isMissingTransactionPart(pendingValuePaths);
     if (!newestTime) return;
 
@@ -111,4 +106,4 @@ export function waitIfReceivedIncompleteTransaction(watcher: SyncWatcher) {
     // ALSO! Plus the hash I think only stores like 48 bits. So the chance of collision is somewhat high, especially if we're accessing thousands of paths. So sometimes this will trigger even though we're not missing any part just because we had a collision between the path hashes. 
     proxyWatcher.triggerOnPromiseFinish(promise, { waitReason: "Missing transaction part" });
     console.warn(`Waiting for missing transaction part ${newestTime.path} which was written at time ${newestTime.time} (now is ${now}). We have parts of this transaction, but we are missing this specific path.`);
-}
+});

package/src/2-proxy/callLevelCache.ts

@@ -0,0 +1,71 @@
+import { proxyWatcher } from "./PathValueProxyWatcher";
+import { isDirectChildPathStr } from "../path";
+
+type CallLevelCacheEntry<Result> = {
+    result: Result;
+    // Every path getCallback saw while the wrapped function ran. A set to exactly one of these invalidates the entry.
+    reads: Set<string>;
+    // Every path getKeys saw. A set to a DIRECT CHILD of one of these invalidates the entry (a new or deleted child changes the keys).
+    keyReads: string[];
+};
+
+/** Caches a function on synchronized data for the lifespan of a single watcher evaluation — one synchronous run of a watcher function, NOT a whole function call (which can re-run many times). The gets the function makes are recorded, and any set within the same evaluation that lands on one of them (or on a direct child of a getKeys it made) invalidates the entry, so the cache can never return a value the evaluation itself has made stale. Outside an evaluation the wrapped function is simply called through.
+ *
+ * Each live entry costs a comparison per set for the rest of the evaluation, so this is for functions called many times per evaluation with few distinct arguments — not a general memoizer. */
+export function callLevelCache<Args extends unknown[], Result>(fnc: (...args: Args) => Result): (...args: Args) => Result {
+    let cachedEvaluationId = -1;
+    let entries = new Map<string, CallLevelCacheEntry<Result>>();
+    let hasSetCallback = false;
+
+    function onSet(pathStr: string): void {
+        for (let [key, entry] of entries) {
+            if (setInvalidatesEntry(entry, pathStr)) {
+                entries.delete(key);
+            }
+        }
+    }
+
+    return function callLevelCached(...args: Args): Result {
+        let evaluationId = proxyWatcher.getEvaluationId();
+        if (evaluationId === undefined) return fnc(...args);
+        if (evaluationId !== cachedEvaluationId) {
+            cachedEvaluationId = evaluationId;
+            entries = new Map();
+            // The previous evaluation's set callback was auto-unregistered when it ended.
+            hasSetCallback = false;
+        }
+        let key = JSON.stringify(args);
+        let existing = entries.get(key);
+        if (existing) return existing.result;
+        let reads = new Set<string>();
+        let keyReads: string[] = [];
+        let unregisterGet = proxyWatcher.onEvaluationGet(pathStr => {
+            reads.add(pathStr);
+        });
+        let unregisterGetKeys = proxyWatcher.onEvaluationGetKeys(pathStr => {
+            keyReads.push(pathStr);
+        });
+        let result: Result;
+        try {
+            result = fnc(...args);
+        } finally {
+            unregisterGet();
+            unregisterGetKeys();
+        }
+        entries.set(key, { result, reads, keyReads });
+        if (!hasSetCallback) {
+            hasSetCallback = true;
+            proxyWatcher.onEvaluationSet(onSet);
+        }
+        return result;
+    };
+}
+
+function setInvalidatesEntry(entry: CallLevelCacheEntry<unknown>, pathStr: string): boolean {
+    if (entry.reads.has(pathStr)) return true;
+    // Iterate the (very few) getKeys paths, rather than deriving the set path's parent and looking it up — isDirectChildPathStr does its cheap rejections before paying for the derive.
+    for (let keyReadPath of entry.keyReads) {
+        if (isDirectChildPathStr(keyReadPath, pathStr)) return true;
+    }
+    return false;
+}

package/src/3-path-functions/PathFunctionRunner.ts

@@ -802,6 +802,7 @@ export class PathFunctionRunner {
                     noWaitForCommit: true,
                     debugName: debugName,
                     source: debugName,
+                    // NOTE: Run at time is needed not just so we read at a specific time, but it's also needed for rejections. We could technically make it so that the read of the result that we use for rejections always happens at a specific time and not set this in certain cases. But then, even then, we'll probably run into problems with the secondary runners trying to run the call because they think it's stuck. We should just make our calls faster by splitting them up. 
                     runAtTime: callSpec.runAtTime,
                     getPermissionsCheck: PermissionsChecker && (() => new PermissionsChecker(callSpec)),
                     nestedCalls: "inline",
@@ -813,7 +814,7 @@ export class PathFunctionRunner {
                         stats.totalInternalLoopCount++;
                         functionCallInnerCount++;
                         if (PathFunctionRunner.DEBUG_CALLS) {
-                            console.log(`Evaluating (try count ${runCount}) ${debugNameColored}`);
+                            console.log(`Evaluating (try count ${runCount}, ${proxyWatcher.getTriggeredWatcherMaybeUndefined()?.lastWatches.paths.size ?? 0} paths) ${debugNameColored}`);
                         }
                         if (runCount > PathFunctionRunner.MAX_WATCH_LOOPS) {
                             let errorMessage = `MAX_WATCH_LOOPS exceeded for ${debugNameColored}. All accesses have to be consistent. So Querysub.time() instead of Date.now() and Querysub.nextId() instead of nextId() / Math.random(). If you need multiple random numbers, keep track of an index, and pass it to Querysub.nextId() for the nth random number.`;

package/src/3-path-functions/syncSchema.ts

@@ -166,7 +166,20 @@ export type PermissionsParameters = {
  *      of undefined, and a time of 0.
  
  */
-export type PermissionsCallback = (config: PermissionsParameters) => PermissionsCheckResult;
+export type PermissionsCallback = ((config: PermissionsParameters) => PermissionsCheckResult) & {
+    /** The check's result cannot change within a single call, so it may be cached for the call's lifetime (see the callImmutable cache in permissions.ts). Technically user permissions CAN change during a call — but every call that changes them must simply do nothing afterwards, so nothing ever acts on a result the change made stale. The functions that change user permissions carry a note saying exactly that. */
+    callImmutable?: boolean;
+};
+
+/** Restricts nothing itself (every ancestor check still applies) — its only purpose is to give a collection a LEAF permissions path, so checks under it resolve there instead of to a non-leaf ancestor and become cacheable for the call (see the callImmutable cache in permissions.ts). Use it on a collection whose siblings carry deeper rules:
+ *      permissions: {
+ *          PERMISSIONS: isRegisteredUserPERMISSIONS,
+ *          myCollection: { PERMISSIONS: leafCachePERMISSIONS },
+ *          myCollectionInternal: { PERMISSIONS: isSuperUserPERMISSIONS },
+ *      }
+ */
+export const leafCachePERMISSIONS: PermissionsCallback = () => true;
+leafCachePERMISSIONS.callImmutable = true;
 export type PermissionsCheckResult = boolean | { allowed: boolean; skipParentChecks?: boolean; };
 /*
     NOTE: All ancestor permissions checks are applied as well.

package/src/4-querysub/permissions.ts

@@ -1,6 +1,6 @@
-import { cache, cacheArgsEqual, cacheLimited } from "socket-function/src/caching";
+import { cache, cacheArgsEqual, cacheJSONArgsEqual, cacheLimited } from "socket-function/src/caching";
 import { measureFnc, measureWrap, nameFunction } from "socket-function/src/profiling/measure";
-import { getPathSuffix, getPathDepth, trimPathStrToDepth, getPathFromStr, rootPathStr, getPathIndex, getPathStr1, joinPathStres, appendToPathStr, getPathStr } from "../path";
+import { getPathSuffix, getPathDepth, trimPathStrToDepth, getPathFromStr, rootPathStr, getPathIndex, getPathStr1, isSameOrChildPathStr, joinPathStres, appendToPathStr, getPathStr } from "../path";
 import { atomic, atomicObjectRead, isSynced, proxyWatcher } from "../2-proxy/PathValueProxyWatcher";
 import { SchemaObject, getSchemaObject, hasWildcardMatch, getWildcardMatches, PERMISSIONS_FUNCTION_ID, PermissionsCheckResult, getDevelopmentModule } from "../3-path-functions/syncSchema";
 import { getModuleFromConfig } from "../3-path-functions/pathFunctionLoader";
@@ -30,6 +30,28 @@ function watchModule(config: FunctionSpec): NodeJS.Module | undefined {
 
 const callPermissionsPath = getPathStr1(CALL_PERMISSIONS_KEY);
 
+// How many callImmutable results a single call may hold before the whole set resets. Every live entry costs a prefix comparison on EVERY permissions check, so a big cache makes everything slower — a small one that occasionally resets stays a pure win.
+const CALL_IMMUTABLE_RESULTS_LIMIT = 32;
+// A non-cacheable permissions path re-runs its rule callbacks on every single check. Once one is hit this many times within a call it is a real cost, so we warn — and again at every further multiple, so the scale of the problem stays visible.
+const NON_CACHEABLE_WARN_INTERVAL = 100;
+// The warning includes the source of each check missing its callImmutable flag; rule callbacks are usually short, but a long one shouldn't flood the log.
+const NON_CALL_IMMUTABLE_SOURCE_MAX_LENGTH = 500;
+
+// The spec is pure data derived from (domainName, moduleId), but building it inline gave it a fresh identity per call — which defeated perSchema (cacheArgsEqual compares by ===), recreating PermissionsCheckSchema and its checkCache on EVERY check on dev deployments. Resolving through here hands back the same object every time, so all the downstream caches hit.
+const getDevelopmentFunctionSpec = cacheJSONArgsEqual(function getDevelopmentFunctionSpec(domainName: string, moduleId: string): FunctionSpec {
+    return {
+        DomainName: domainName,
+        ModuleId: moduleId,
+        FunctionId: PERMISSIONS_FUNCTION_ID,
+        exportPathStr: callPermissionsPath,
+        // NOTE: These SHOULDN'T be required, as we don't commit this function to the FunctionRunner,
+        //  we just use this to run the function on the local machine.
+        FilePath: "LOCAL_PERMISSIONS_HACK",
+        gitURL: "LOCAL_PERMISSIONS_HACK",
+        gitRef: "LOCAL_PERMISSIONS_HACK",
+    };
+}, 1000 * 100);
+
 /** NOTE: This can only be used synchronously, and must be recreated after the current
  *      synchronous code is finished.
  */
@@ -57,17 +79,7 @@ export class PermissionsCheck {
                 schema: SchemaObject;
                 fnc: FunctionSpec;
             } | undefined {
-                let fnc: FunctionSpec = {
-                    DomainName: domainName,
-                    ModuleId: moduleId,
-                    FunctionId: PERMISSIONS_FUNCTION_ID,
-                    exportPathStr: callPermissionsPath,
-                    // NOTE: These SHOULDN'T be required, as we don't commit this function to the FunctionRunner,
-                    //  we just use this to run the function on the local machine.
-                    FilePath: "LOCAL_PERMISSIONS_HACK",
-                    gitURL: "LOCAL_PERMISSIONS_HACK",
-                    gitRef: "LOCAL_PERMISSIONS_HACK",
-                };
+                let fnc = getDevelopmentFunctionSpec(domainName, moduleId);
                 let modulePermissions = getDevelopmentModule(moduleId);
                 if (!modulePermissions) {
                     getDevelopmentModule(moduleId);
@@ -122,11 +134,81 @@ export class PermissionsCheck {
         callExamplePath: string;
         emptyKeyPath: string;
     }>();
+    // Leaf, all-callImmutable results, checked by prefix before anything else. Capped: every live entry is a comparison per check, so past the cap the whole thing resets rather than making every check slower.
+    private callImmutableResults = new Map<string, boolean>();
+    private registeredCallImmutableReset = false;
+    private ensureCallImmutableResetRegistered(): void {
+        if (this.registeredCallImmutableReset) return;
+        this.registeredCallImmutableReset = true;
+        // onAfterTriggered is the immediate end-of-call reset — it fires when this run finishes. onInnerDisposed would wait until the call is fully synchronized, which is too late: the next run must recheck.
+        proxyWatcher.getTriggeredWatcherMaybeUndefined()?.onAfterTriggered.push(() => {
+            this.callImmutableResults.clear();
+            this.callImmutableExactResults.clear();
+            this.nonCacheableCounts.clear();
+        });
+    }
+    private addCallImmutableResult(permissionsPath: string, allowed: boolean): void {
+        this.ensureCallImmutableResetRegistered();
+        if (this.callImmutableResults.size >= CALL_IMMUTABLE_RESULTS_LIMIT) this.callImmutableResults.clear();
+        this.callImmutableResults.set(permissionsPath, allowed);
+    }
+
+    // Non-leaf permissions paths with all-callImmutable checks, cached by the EXACT path checked. A child of a non-leaf path may resolve to a deeper rule, so no prefix matching — but the same path always resolves the same way, so an equality hit is sound. The hottest case is the module's Data root, which every write's parent-marker walk checks and which can never be a leaf (every rule sits below it). Unlimited, because lookups are a Map.get — unlike the prefix cache, size costs the other checks nothing.
+    private callImmutableExactResults = new Map<string, { permissionsPath: string; allowed: boolean }>();
+    private addCallImmutableExactResult(path: string, permissionsPath: string, allowed: boolean): void {
+        this.ensureCallImmutableResetRegistered();
+        this.callImmutableExactResults.set(path, { permissionsPath, allowed });
+    }
+
+    // How often checks have resolved to each non-cacheable permissions path this call. Reset with the results above. Non-cacheable checks re-run their rule callbacks every time, so a hot one is the exact problem the callImmutable cache exists to prevent — count it and say so.
+    private nonCacheableCounts = new Map<string, number>();
+    private countNonCacheableCheck(path: string, permissionsPath: string, nonCallImmutableSources: string[]): void {
+        this.ensureCallImmutableResetRegistered();
+        let count = (this.nonCacheableCounts.get(permissionsPath) || 0) + 1;
+        this.nonCacheableCounts.set(permissionsPath, count);
+        if (count % NON_CACHEABLE_WARN_INTERVAL !== 0) return;
+        // The unmarked checks themselves, because their source usually makes it obvious whether they are actually call-immutable — and says exactly which function to go mark. Empty means every check IS marked, so the problem must be leaf-ness.
+        let sourcesText = "";
+        if (nonCallImmutableSources.length > 0) {
+            sourcesText = `\nThe checks NOT marked callImmutable:\n` + nonCallImmutableSources.map(source => `    ${source.slice(0, NON_CALL_IMMUTABLE_SOURCE_MAX_LENGTH)}`).join("\n");
+        }
+        console.warn(red(
+            `Many permission checks (${count} this call) on paths which resolve to the non-cacheable permissions path "${permissionsPath}" (most recently the path "${path}"). `
+            + `A result is only cacheable when the permissions path is a leaf (no rules below it) AND every check that runs for it is marked callImmutable. `
+            + `Either your permissions are legitimately complicated (a unique check per path, which is simply slow), `
+            + `or a rule is missing its callImmutable flag, `
+            + `or these paths have no leaf rule of their own and are resolving to a non-leaf ancestor — `
+            + `adding a level of nesting with leafCachePERMISSIONS adds a redundant (allow-everything) check, but gives the paths a leaf so the result is cached for the rest of the call:\n`
+            + `    permissions: {\n`
+            + `        PERMISSIONS: isRegisteredUserPERMISSIONS,\n`
+            + `        myCollection: { PERMISSIONS: leafCachePERMISSIONS },\n`
+            + `        myCollectionInternal: { PERMISSIONS: isSuperUserPERMISSIONS },\n`
+            + `    }`
+            + sourcesText
+        ));
+    }
+
     // IMPORTANT! This function USED TO BE a major hotspot for function evaluation, and so is heavily optimized.
+    @measureFnc
     public checkPermissions(path: string): { permissionsPath: string; allowed: boolean; } {
         if (this.dead) throw new Error("PermissionsCheck MUST be used synchronously, after which it cannot be reused");
         if (PermissionsCheck.skippingChecks) return { permissionsPath: rootPathStr, allowed: true };
 
+        if (this.callImmutableExactResults.size > 0) {
+            let exact = this.callImmutableExactResults.get(path);
+            if (exact) {
+                return { permissionsPath: exact.permissionsPath, allowed: exact.allowed };
+            }
+        }
+        // The cached permissions paths are leaves, so anything at or under one resolves to it — a prefix check IS the whole resolution.
+        if (this.callImmutableResults.size > 0) {
+            for (let [cachedPath, allowed] of this.callImmutableResults) {
+                if (isSameOrChildPathStr(cachedPath, path)) {
+                    return { permissionsPath: cachedPath, allowed };
+                }
+            }
+        }
+
         let pathPrefix = trimPathStrToDepth(path, DEPTH_TO_DATA);
         let pathParts = this.pathPartsCache.get(pathPrefix);
         if (!pathParts) {
@@ -177,7 +259,15 @@ export class PermissionsCheck {
         }
         if (rootKey === "Data") {
             let dataPath = getPathSuffix(path, DEPTH_TO_DATA);
-            return instance.checkPermissionsBase(dataPath);
+            let result = instance.checkPermissionsBase(dataPath);
+            if (result.callCacheable) {
+                this.addCallImmutableResult(result.permissionsPath, result.allowed);
+            } else if (result.allCallImmutable) {
+                this.addCallImmutableExactResult(path, result.permissionsPath, result.allowed);
+            } else {
+                this.countNonCacheableCheck(path, result.permissionsPath, result.nonCallImmutableSources);
+            }
+            return result;
         }
         return { permissionsPath: path, allowed: false };
     }
@@ -216,6 +306,7 @@ class PermissionsCheckSchema {
     /** Converts a specific path to a more general path. All paths which map to this general path
      *      will have identical permissions checks.
      */
+    @measureFnc
     private getCachePermissionsPath(path: string): string {
         if (this.schema.permissionsNonWildcards.has(path)) {
             return path;
@@ -244,7 +335,7 @@ class PermissionsCheckSchema {
     // NOTE: For our trivial "127.0.0.1" check this cache isn't needed. But permissions checks might be A LOT slower,
     //  so it is important to cache it based on the permissionsPath.
     private checkCache = cacheLimited(1000 * 1000, measureWrap((permissionsPath: string) => {
-        let checks = this.getChecks(permissionsPath);
+        let { checks, allCallImmutable, nonCallImmutableSources } = this.getChecks(permissionsPath);
         let allowed = overrideCurrentCall({
             spec: this.exampleCall,
             fnc: this.fnc,
@@ -286,32 +377,73 @@ class PermissionsCheckSchema {
                 return true;
             });
         });
-        return { permissionsPath: joinPathStres(this.pathPrefix, permissionsPath), allowed };
+        return {
+            permissionsPath: joinPathStres(this.pathPrefix, permissionsPath),
+            allowed,
+            // A leaf with only callImmutable checks means any path at or under permissionsPath resolves to this same result for the rest of the call, so the caller may cache it (see addCallImmutableResult). All-callImmutable WITHOUT the leaf still allows exact-path caching (addCallImmutableExactResult).
+            callCacheable: allCallImmutable && this.isLeafPermissionsPath(permissionsPath),
+            allCallImmutable,
+            nonCallImmutableSources,
+        };
     }, "permissionsCheckInsideCache"));
 
-    public checkPermissionsBase(dataPath: string): { permissionsPath: string; allowed: boolean; } {
+    @measureFnc
+    public checkPermissionsBase(dataPath: string): { permissionsPath: string; allowed: boolean; callCacheable: boolean; allCallImmutable: boolean; nonCallImmutableSources: string[]; } {
         let permissionsPath = this.getCachePermissionsPath(dataPath);
         return this.checkCache(permissionsPath);
     }
+
+    // A permissions path is a leaf when NO rule sits strictly below it. That is what makes caching by prefix sound: with no deeper rules, every path at or under the leaf resolves to the leaf itself, so one cached result answers all of them.
+    private isLeafPermissionsPath = cacheLimited(1000 * 1000, (permissionsPath: string): boolean => {
+        for (let rulePath of this.schema.permissionsNonWildcards.keys()) {
+            if (rulePath.length <= permissionsPath.length) continue;
+            if (isSameOrChildPathStr(permissionsPath, rulePath)) return false;
+        }
+        if (this.schema.permissionsWildcards.length > 0) {
+            let depth = getPathDepth(permissionsPath);
+            let parts = getPathFromStr(permissionsPath);
+            for (let wildcardCheck of this.schema.permissionsWildcards) {
+                if (wildcardCheck.pathParts.length <= depth) continue;
+                // A deeper wildcard only breaks leaf-ness if it can actually match a descendant, which requires its first `depth` parts to match ours.
+                let couldMatchChild = true;
+                for (let i = 0; i < depth; i++) {
+                    if (wildcardCheck.pathParts[i] === "*") continue;
+                    if (wildcardCheck.pathParts[i] !== parts[i]) {
+                        couldMatchChild = false;
+                        break;
+                    }
+                }
+                if (couldMatchChild) return false;
+            }
+        }
+        return true;
+    });
     // NOTE: We don't cache the result of a permissions check, because it might change while
     //  a function is evaluating. If they need to be skipped for the purposes of speed (which is hard
     //  to believe, considering all the other sources of overhead we have), skipPermissionsChecks
     //  can be used to quickly skip them.
-    private getChecks = cacheLimited(1000 * 1000, ((path: string): (() => PermissionsCheckResult)[] => {
+    private getChecks = cacheLimited(1000 * 1000, measureWrap((path: string): { checks: (() => PermissionsCheckResult)[]; allCallImmutable: boolean; nonCallImmutableSources: string[] } => {
         let checks: {
             check: () => PermissionsCheckResult;
             path: string;
         }[] = [];
+        let allCallImmutable = true;
+        let nonCallImmutableSources: string[] = [];
         let depth = getPathDepth(path);
         for (let i = depth; i >= 0; i--) {
             let ancestorPath = trimPathStrToDepth(path, i);
             const permissions = this.schema.permissionsNonWildcards.get(ancestorPath);
             if (permissions) {
-                let check = () => permissions({
+                if (!permissions.callImmutable) {
+                    allCallImmutable = false;
+                    nonCallImmutableSources.push(permissions.toString());
+                }
+                // Named by the rule it came from, so the table says WHICH permission is doing the reading rather than just that permissions are slow. Built once per generalized path (this is inside a cache), so the wrapper is not rebuilt per check.
+                let check = measureWrap(() => permissions({
                     callerMachineId: this.callerConfig.machineID,
                     matchedPath: ancestorPath,
                     pathWildcards: [],
-                });
+                }), `permissionsRule ${ancestorPath}`);
                 if (PermissionsCheck.DEBUG) {
                     Object.assign(check, { debugName: ancestorPath });
                 }
@@ -323,12 +455,17 @@ class PermissionsCheckSchema {
         for (let wildcardCheck of this.schema.permissionsWildcards) {
             let matches = getWildcardMatches(wildcardCheck.pathParts, getPathFromStr(path));
             if (!matches) continue;
+            if (!wildcardCheck.callback.callImmutable) {
+                allCallImmutable = false;
+                nonCallImmutableSources.push(wildcardCheck.callback.toString());
+            }
             let matchedPath = trimPathStrToDepth(path, wildcardCheck.pathParts.length);
-            let check = () => wildcardCheck.callback({
+            // Named by the wildcard pattern rather than the path it matched, so every path a rule covers aggregates into one row instead of one row per key.
+            let check = measureWrap(() => wildcardCheck.callback({
                 callerMachineId: this.callerConfig.machineID,
                 matchedPath,
                 pathWildcards: matches || [],
-            });
+            }), `permissionsRule ${wildcardCheck.pathParts.join(".")}`);
             if (PermissionsCheck.DEBUG) {
                 Object.assign(check, { debugName: wildcardCheck.pathParts.join(".") });
             }
@@ -337,6 +474,6 @@ class PermissionsCheckSchema {
 
         sort(checks, x => -x.path.length);
 
-        return checks.map(x => x.check);
-    }));
+        return { checks: checks.map(x => x.check), allCallImmutable, nonCallImmutableSources };
+    }, "permissionsGetChecksInsideCache"));
 }

package/src/diagnostics/SyncTestPage.tsx

@@ -17,7 +17,8 @@ import { PathAuditerController } from "./pathAuditer";
 import { t } from "../2-proxy/schema2";
 import { proxyWatcher } from "../2-proxy/PathValueProxyWatcher";
 import { remoteWatcher } from "../1-path-client/RemoteWatcher";
-import { getAllPendingPathValueReads, isMissingTransactionPart, waitIfReceivedIncompleteTransaction } from "../2-proxy/TransactionDelayer";
+import { isMissingTransactionPart } from "../2-proxy/TransactionDelayer";
+import { createMissingEpochValue, PathValue } from "../0-path-value-core/pathValueCore";
 
 module.hotreload = true;
 
@@ -290,6 +291,27 @@ export class SyncTestPage extends qreact.Component {
     }
 }
 
+// A diagnostic wants every pending read, so this is the unfiltered version — TransactionDelayer's own copy filters by time as it loops, which is why it stopped being shared.
+function getAllPendingPathValueReads(watcher = proxyWatcher.getTriggeredWatcher()) {
+    let values: PathValue[] = [];
+    for (let map of watcher.pendingAccesses.values()) {
+        for (let pathValue of map.values()) {
+            values.push(pathValue.pathValue);
+        }
+    }
+    // NOTE: These can't contribute the transaction paths, but they do contribute their path and their time, which will cause other transaction paths to know that they are invalid.
+    let allEpochPaths = new Set<string>();
+    for (let paths of watcher.pendingEpochAccesses.values()) {
+        for (let path of paths) {
+            allEpochPaths.add(path);
+        }
+    }
+    for (let path of allEpochPaths) {
+        values.push(createMissingEpochValue(path));
+    }
+    return values;
+}
+
 
 class SyncTestControllerBase {
     async test() {

package/src/library-components/URLParam.ts

@@ -208,7 +208,6 @@ function syncStateToURL() {
         window.history.pushState({}, "", targetURL);
     });
     Querysub.createWriteWatcher(function syncStateToURL() {
-        console.log("syncStateToURL", Querysub.getTriggerReason());
         let urlObj = new URL(document.location.href);
         urlObj.search = encodeSearchString(data().params, data().defaults);
         targetURL = urlObj.toString();

package/src/path.ts

@@ -171,6 +171,18 @@ export function getParentPathStr(pathStr: string) {
     return pathStr.slice(0, getStartOfLastPart(pathStr));
 }
 
+/** True when childPathStr is pathStr itself or any descendant of it. Every path str ends in the delimiter, so a plain prefix check cannot mistake a sibling with a longer key (".,ab.," is not a prefix of ".,abc.,"). */
+export function isSameOrChildPathStr(pathStr: string, childPathStr: string): boolean {
+    return childPathStr.startsWith(pathStr);
+}
+
+/** True when childPathStr is EXACTLY one level below pathStr. The cheap length and prefix rejections run first, so the parent derivation is only paid once they pass. */
+export function isDirectChildPathStr(pathStr: string, childPathStr: string): boolean {
+    if (childPathStr.length <= pathStr.length) return false;
+    if (!childPathStr.startsWith(pathStr)) return false;
+    return getParentPathStr(childPathStr) === pathStr;
+}
+
 /** === getPathFromStr(pathStr).slice(-1)[0] || "" */
 export function getLastPathPart(pathStr: string) {
     let lastPartIndex = pathStr.lastIndexOf(pathDelimitEscaped);

package/src/user-implementation/userData.ts

@@ -1,11 +1,12 @@
 import { atomic, atomicObjectWrite } from "../2-proxy/PathValueProxyWatcher";
+import { callLevelCache } from "../2-proxy/callLevelCache";
 import { Querysub } from "../4-querysub/Querysub";
 import { red } from "socket-function/src/formatting/logColors";
 import { isNode, sha256Hash, timeInHour } from "socket-function/src/misc";
 import { registerAliveChecker } from "../2-proxy/garbageCollection";
 import { generateLoginEmail } from "./loginEmail";
 import { logErrors } from "../errors";
-import { PermissionsParameters } from "../3-path-functions/syncSchema";
+import { PermissionsCallback, PermissionsParameters } from "../3-path-functions/syncSchema";
 import { sendEmail_postmark } from "../email_ims_notifications/postmark";
 import { isClient } from "../config2";
 import { getExternalIP } from "../misc/networking";
@@ -438,6 +439,11 @@ export function isAdminUserPERMISSIONS(): boolean {
 export function isModeratorUserPERMISSIONS(): boolean {
     return createUserPERMISSIONS("moderator")();
 }
+// A user's type does not change within a call, so these results may be cached for the call's lifetime (permissions.ts caches leaf paths whose checks all carry this). Technically it CAN change (specialSetUserType) — but a call that changes a user's type must do nothing after the change, so no caller ever acts on a cached result the change made stale. specialSetUserType carries the matching note.
+isRegisteredUserPERMISSIONS.callImmutable = true;
+isSuperUserPERMISSIONS.callImmutable = true;
+isAdminUserPERMISSIONS.callImmutable = true;
+isModeratorUserPERMISSIONS.callImmutable = true;
 
 export function isCurrentUserSuperUser() {
     return isSuperUserPERMISSIONS();
@@ -451,6 +457,17 @@ export function satisifiedUserType(currentType: UserType, minimumType: UserType)
     return currentType === minimumType || userTypeRanking[currentType] > userTypeRanking[minimumType];
 }
 
+export function createWildcardUserPERMISSIONS(config: { wildcardIndex: number; allowSuperUser?: boolean; }): PermissionsCallback {
+    let check: PermissionsCallback = permissionsConfig => {
+        if (config.allowSuperUser && isSuperUserPERMISSIONS()) return true;
+        let userId = getUserIdAllowUndefined();
+        if (!userId) return false;
+        return permissionsConfig.pathWildcards[config.wildcardIndex] === userId;
+    };
+    check.callImmutable = true;
+    return check;
+}
+
 export function createUserPERMISSIONS(userType: UserType) {
     return () => {
         let allowed = isCurrentUserType(userType);
@@ -523,9 +540,8 @@ export function assertUserType(userType: UserType) {
     }
 }
 
-export const getUserIdAllowUndefined = getCurrentUser;
-export const getUserId = getCurrentUserAssert;
-export function getCurrentUser(config?: { ignoreImpersonate?: boolean; }): string | undefined {
+// Called constantly (every permissions check goes through it), on data that almost never changes within one evaluation — exactly what callLevelCache is for.
+export const getCurrentUser = callLevelCache(function getCurrentUser(config?: { ignoreImpersonate?: boolean; }): string | undefined {
     if (!isNode()) {
         // NOTE: This check runs clientside, so it doesn't need to verify they are allowed to impersonate
         //  (the user can pretend to be anyone on their machine, the server will just ignore it).
@@ -544,7 +560,9 @@ export function getCurrentUser(config?: { ignoreImpersonate?: boolean; }): strin
         return undefined;
     }
     return identifiedUserId;
-}
+});
+export const getUserIdAllowUndefined = getCurrentUser;
+export const getUserId = getCurrentUserAssert;
 export const user = getCurrentUserAssert;
 export const userAssert = getCurrentUserAssert;
 export function getCurrentUserAssert(): string {
@@ -565,7 +583,8 @@ function getLoadingUserObj() {
     };
 }
 
-export function getCurrentUserObj(): User | undefined {
+// Returns a proxy, which is safe to cache within one evaluation: a write that CHANGES which user object this resolves to also hits a path this read (machineSecure, the users key) and invalidates the entry, while a write inside the user object leaves the proxy itself still valid.
+export const getCurrentUserObj = callLevelCache(function getCurrentUserObj(): User | undefined {
     let userId = getCurrentUser();
 
     if (!userId || userId === "loadinguser") {
@@ -593,7 +612,7 @@ export function getCurrentUserObj(): User | undefined {
         return getLoadingUserObj();
     }
     return users[userId];
-}
+});
 export const getUserObj = getCurrentUserObjAssert;
 export const getUserObjAssert = getCurrentUserObjAssert;
 export function getCurrentUserObjAssert() {
@@ -1059,6 +1078,7 @@ function specialSetInviteCount(config: { userId: string; count: number; }) {
     data().users[config.userId].invitesRemaining = config.count;
     logActivity({ type: "setInviteCount", fields: { userId: config.userId, count: config.count } });
 }
+// IMPORTANT! This changes the user's permissions, and the user permission checks are marked callImmutable — callers everywhere assume "registered user" / "super user" cannot change during a call, and cached results are only reset when the call ends. So this must stay the LAST thing its call does: do not add work after the write here, and do not call this and then keep going.
 function specialSetUserType(config: { userId: string; userType: UserType; }) {
     assertUserType("superuser");
     data().users[config.userId].userType = config.userType;