@feltdb/core 0.6.9 → 0.6.10

package/dist/cli/commands.js

@@ -7,7 +7,7 @@ import http from 'http';
 import net from 'net';
 import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
-import { createFeltDB, diffFlowSpec, formatFlowSpec, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
+import { createFeltDB, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
 import { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
 import { detectApplication, discoverApplicationUrl } from './application.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
@@ -55,6 +55,8 @@ export async function handleCommand(command, args) {
             return handleWorkspace(args);
         case 'dev':
             return handleDev(args);
+        case 'investigations':
+            return handleInvestigations(args);
         case 'build':
             return handleBuild(args);
         case 'check':
@@ -76,6 +78,92 @@ export async function handleCommand(command, args) {
             return handleHelp();
     }
 }
+/**
+ * Inspect the durable investigation store.
+ *
+ * The evidence chain is only useful if a developer can get back to it after
+ * the browser is closed, so it is queryable from the command line.
+ */
+function handleInvestigations(args) {
+    if (args.includes('--help')) {
+        console.log('Usage: feltdb investigations [<investigation-id>] [--json]\n');
+        console.log('List durable runtime investigations, or show one in full.\n');
+        console.log('Options:');
+        console.log('  --json    Emit machine-readable JSON');
+        return;
+    }
+    const store = new InvestigationLifecycleManager(process.cwd());
+    const json = args.includes('--json');
+    const id = args.find(value => !value.startsWith('--'));
+    if (id) {
+        const investigation = store.loadInvestigation(id);
+        if (!investigation)
+            throw new Error(`Investigation not found: ${id}`);
+        if (json) {
+            console.log(JSON.stringify(investigation, null, 2));
+            return;
+        }
+        const observation = investigation.originalObservation;
+        console.log(`\nInvestigation ${investigation.id}`);
+        console.log(`  Workspace:    ${investigation.workspaceId}`);
+        console.log(`  Investigation ${investigation.investigationState}`);
+        console.log(`  Remediation:  ${investigation.remediationState}`);
+        console.log(`  Verification: ${investigation.verificationState}\n`);
+        if (observation) {
+            console.log('Observation');
+            console.log(`  ${observation.method} ${observation.url} -> HTTP ${observation.status}`);
+            console.log(`  ${observation.browser || 'unknown'} / ${observation.runtime || 'unknown'}`
+                + `${observation.durationMs !== undefined ? ` / ${observation.durationMs}ms` : ''}\n`);
+        }
+        if (investigation.evidence?.length) {
+            console.log('Evidence (observed by the runtime)');
+            for (const item of investigation.evidence)
+                console.log(`  [${item.kind}] ${item.statement}`);
+            console.log();
+        }
+        if (investigation.finding) {
+            console.log('Finding (FeltDB analysis, not an observation)');
+            console.log(`  ${investigation.finding.statement}`);
+            console.log(`  confidence: ${investigation.finding.confidence}\n`);
+        }
+        if (investigation.remediation?.changeIdentity) {
+            console.log('Remediation');
+            console.log(`  ${investigation.remediation.changeKind}: ${investigation.remediation.changeIdentity}`);
+            if (investigation.remediation.changedPaths.length) {
+                console.log(`  changed: ${investigation.remediation.changedPaths.join(', ')}`);
+            }
+            console.log();
+        }
+        if (investigation.verificationAttempt) {
+            const attempt = investigation.verificationAttempt;
+            console.log('Verification');
+            console.log(`  ${attempt.result}: ${attempt.summary}`);
+            console.log(`  ${attempt.originalStatus} -> ${attempt.observedStatus ?? 'no matching observation'}\n`);
+        }
+        return;
+    }
+    const investigations = store.listInvestigations();
+    if (json) {
+        console.log(JSON.stringify(investigations, null, 2));
+        return;
+    }
+    if (investigations.length === 0) {
+        console.log('\nNo investigations recorded.');
+        console.log('Run "feltdb dev", exercise the application, and a runtime defect will open one.\n');
+        return;
+    }
+    console.log(`\n${investigations.length} investigation${investigations.length === 1 ? '' : 's'}\n`);
+    for (const investigation of investigations) {
+        const observation = investigation.originalObservation;
+        const summary = observation
+            ? `${observation.method} ${observation.url} -> ${observation.status}`
+            : investigation.observationId;
+        console.log(`  ${investigation.id}  ${investigation.verificationState.padEnd(12)} ${summary}`);
+    }
+    const metrics = store.metrics();
+    console.log(`\n  ${metrics.observations} observations, ${metrics.evidenceRecords} evidence records, `
+        + `${metrics.serializedBytes} bytes, loaded in ${metrics.loadMilliseconds}ms\n`);
+}
 function flowFile(args) {
     const candidate = args.find(value => !value.startsWith('--')) || 'feltdb.flow';
     return path.resolve(candidate);
@@ -414,37 +502,29 @@ async function handleWorkspaceConnect(args) {
     console.log('   This feature will be implemented in the next phase');
     console.log('   (when @feltdb/client workspace APIs are available)\n');
 }
-function runLocalVite(args, waitForExit) {
-    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const child = spawn(executable, ['exec', '--', 'vite', ...args], {
-        cwd: process.cwd(),
-        stdio: 'inherit',
-        env: process.env,
-    });
-    if (!waitForExit)
-        return child;
-    return new Promise((resolve, reject) => {
-        child.once('error', reject);
-        child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Vite exited with status ${code ?? 'unknown'}`)));
-    });
-}
 async function handleDev(args) {
     var _a, _b, _c;
+    const projectDir = process.cwd();
     if (args.includes('--help')) {
-        console.log('Usage: feltdb dev [--app-url URL | --app-port PORT] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('Usage: feltdb dev [--app-url URL] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('\nOptions:');
+        console.log('  --app-url <url>           Application URL (e.g., http://127.0.0.1:3000)');
+        console.log('  --studio-port <port>      FeltDB Studio port (default: 7701)');
+        console.log('  --authority-port <port>   Authority port (default: 7700)');
+        console.log('  --discovery-port <port>   Pairing discovery port (default: 7799)');
+        console.log('  --no-open                 Do not open Studio in browser');
         return;
     }
     loadProjectEnvironment();
     console.log('🚀 Starting FeltDB development server...\n');
-    const projectDir = process.cwd();
-    const configPath = path.join(projectDir, 'feltdb.config.json');
     // .feltdb/ is reserved local runtime state. Protect it before discovery,
     // initialization, the authority, or pairing can persist anything there.
+    // This runs after `--help` returns, so asking for help never writes anything.
     ensureWorkspaceGitIgnored(projectDir);
+    const configPath = path.join(projectDir, 'feltdb.config.json');
     // Initialize workspace if needed
     let workspace = discoverWorkspace(projectDir);
     if (!workspace) {
-        // Get project name from package.json
         const packageJsonPath = path.join(projectDir, 'package.json');
         let projectId = path.basename(projectDir);
         if (fs.existsSync(packageJsonPath)) {
@@ -460,6 +540,8 @@ async function handleDev(args) {
         console.log(`✨ Initialized Development Workspace`);
         console.log(`   Workspace ID: ${workspace.workspaceId}\n`);
     }
+    // Investigation lifecycle manager will be initialized when needed
+    // const investigationManager = new InvestigationLifecycleManager(projectDir);
     // Create feltdb.config.json if it doesn't exist
     if (!fs.existsSync(configPath)) {
         const packageJsonPath = path.join(projectDir, 'package.json');
@@ -478,11 +560,10 @@ async function handleDev(args) {
             runtime: 'browser',
             storage: 'indexeddb',
             distributed: true,
-            agents: { enabled: false },
-            capabilities: { search: true },
+            applicationUrl: null,
         };
         fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n');
-        console.log(`✨ Created feltdb.config.json with default configuration\n`);
+        console.log(`✨ Created feltdb.config.json\n`);
     }
     const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
     if (config.runtime === 'managed') {
@@ -495,17 +576,15 @@ async function handleDev(args) {
     const runtimeNamespace = config.runtime === 'managed'
         ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
         : config.namespace;
-    const hasAppUrl = args.includes('--app-url');
-    const appUrlArgument = hasAppUrl ? args[args.indexOf('--app-url') + 1] : undefined;
-    if (hasAppUrl && !appUrlArgument)
+    // Application URL precedence:
+    // 1. --app-url (highest priority)
+    // 2. feltdb.config.json applicationUrl
+    // 3. Deterministically discovered running application
+    // 4. No application (lowest priority - allowed)
+    const hasAppUrlArg = args.includes('--app-url');
+    const appUrlArgument = hasAppUrlArg ? args[args.indexOf('--app-url') + 1] : undefined;
+    if (hasAppUrlArg && !appUrlArgument)
         throw new Error('--app-url requires a URL');
-    const hasAppPort = args.includes('--app-port') || args.includes('--port');
-    const appPortValue = args.includes('--app-port')
-        ? args[args.indexOf('--app-port') + 1]
-        : args.includes('--port') ? args[args.indexOf('--port') + 1] : undefined;
-    if (!hasAppUrl && hasAppPort && !appPortValue)
-        throw new Error('--app-port requires a port');
-    const appPort = appPortValue ? Number(appPortValue) : undefined;
     if (appUrlArgument) {
         try {
             const parsed = new URL(appUrlArgument);
@@ -516,28 +595,40 @@ async function handleDev(args) {
             throw new Error(`Invalid --app-url: ${appUrlArgument}`);
         }
     }
-    if (!hasAppUrl && appPortValue && (!Number.isInteger(appPort) || appPort < 1 || appPort > 65535))
-        throw new Error(`Invalid --app-port: ${appPortValue}`);
-    let discoveredApplication;
-    if (!hasAppUrl && !appPort) {
-        discoveredApplication = await discoverApplicationUrl(projectDir);
-    }
-    else {
+    let appUrl;
+    let detectedApplication;
+    // Priority 1: --app-url takes highest priority
+    if (appUrlArgument) {
+        appUrl = appUrlArgument;
         try {
-            discoveredApplication = { project: detectApplication(projectDir) };
+            detectedApplication = detectApplication(projectDir);
         }
         catch {
-            discoveredApplication = { project: { packageManager: 'npm', framework: 'External' } };
+            detectedApplication = { packageManager: 'npm', framework: 'External' };
         }
     }
-    const appUrl = appUrlArgument || (appPort ? `http://127.0.0.1:${appPort}` : discoveredApplication.url);
-    if (!appUrl) {
-        throw new Error('No application URL was detected.\nStart your application and run:\n  feltdb dev --app-url http://127.0.0.1:<port>\nOr configure applicationUrl in feltdb.config.json.');
+    else {
+        // Priority 2: Check feltdb.config.json applicationUrl
+        if (config.applicationUrl) {
+            appUrl = config.applicationUrl;
+            try {
+                detectedApplication = detectApplication(projectDir);
+            }
+            catch {
+                detectedApplication = { packageManager: 'npm', framework: 'External' };
+            }
+        }
+        else {
+            // Priority 3: Try to discover an existing running application
+            const discovered = await discoverApplicationUrl(projectDir);
+            detectedApplication = discovered.project;
+            appUrl = discovered.url;
+        }
     }
     const requestedStudioPort = Number(args.includes('--studio-port') ? args[args.indexOf('--studio-port') + 1] || '7701' : '7701');
     const studioPort = String(await availablePort(requestedStudioPort));
     if (studioPort !== String(requestedStudioPort))
-        console.log(`Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.`);
+        console.log(`⚠ Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.\n`);
     process.env.STUDIO_PORT = studioPort;
     let selfHostedStarted = false;
     let localAuthority = null;
@@ -588,45 +679,69 @@ async function handleDev(args) {
         pairingDiscoveryServer = await startPairingDiscoveryServer(token, discoveryPort);
         pairingToken = token.token;
     }
-    console.log('FeltDB Dev Server');
-    console.log(`  Authority: ${process.env.VITE_FELTDB_URL}`);
-    console.log(`  Studio:    http://127.0.0.1:${studioPort}`);
-    console.log(`  Pairing:   http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
-    console.log('Application');
-    console.log(`  Framework: ${discoveredApplication.project.framework}`);
-    console.log('  Dev command: (managed externally)');
-    console.log(`  URL:       ${appUrl}`);
-    console.log(`  Namespace: ${config.namespace}`);
-    console.log(`  Runtime:   ${config.runtime}`);
-    console.log(`  Storage:   ${config.storage}`);
-    console.log(`  Distributed: ${config.distributed}`);
+    // Output startup information
+    console.log('✨ Development Workspace');
     if (workspace) {
-        console.log(`  Workspace: ${workspace.workspaceId}\n`);
-        console.log(`🔗 Development Workspace`);
-        if (pairingToken) {
-            console.log(`  Pairing Code: ${pairingToken}`);
-            console.log(`  Pairing discovery: http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
-            console.log(`  Clients can use this code to auto-discover the workspace`);
-        }
+        console.log(`   Workspace ID: ${workspace.workspaceId}`);
     }
     console.log();
-    const open = !args.includes('--no-open');
-    console.log(`Application: ${appUrl}`);
-    console.log(`Studio:      http://127.0.0.1:${studioPort}\n`);
-    console.log(`Using existing application at ${appUrl}\n`);
+    console.log('🔗 Development Workspace');
+    if (pairingToken) {
+        console.log(`   Pairing Code: ${pairingToken}`);
+        console.log(`   Pairing discovery: http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
+    }
+    console.log();
+    console.log('FeltDB Dev Server');
+    console.log(`  Namespace:   ${config.namespace}`);
+    console.log(`  Runtime:     ${config.runtime}`);
+    console.log(`  Storage:     ${config.storage}`);
+    console.log(`  Distributed: ${config.distributed}`);
+    console.log();
+    if (appUrl) {
+        console.log(`Application: ${appUrl}`);
+        console.log(`Authority: ${process.env.VITE_FELTDB_URL}`);
+        console.log();
+        console.log(`Using existing application at ${appUrl}`);
+        console.log(`app=${encodeURIComponent(appUrl)}\n`);
+    }
+    else {
+        console.log('❌ No application URL is configured.\n');
+        console.log('Start your application, then run:\n');
+        console.log('  feltdb dev --app-url http://127.0.0.1:<port>\n');
+        console.log('Or set applicationUrl in feltdb.config.json\n');
+        console.log('FeltDB workspace is ready at:');
+        console.log('Authority: ' + process.env.VITE_FELTDB_URL);
+        console.log('Studio:    http://127.0.0.1:' + studioPort);
+        console.log();
+    }
     const stopAll = () => { pairingDiscoveryServer?.close(); void localAuthority?.close(); stopSelfHosted(); };
     process.once('exit', stopAll);
     process.once('SIGINT', () => { stopAll(); process.exit(130); });
     process.once('SIGTERM', () => { stopAll(); process.exit(143); });
+    const open = !args.includes('--no-open');
     await handleStudio([
         '--port', studioPort,
         '--namespace', runtimeNamespace || 'default',
         '--runtime', config.runtime || 'browser',
-        '--app-url', appUrl,
+        ...(appUrl ? ['--app-url', appUrl] : []),
         ...((config.runtime === 'self-hosted' || config.runtime === 'managed') && process.env.VITE_FELTDB_URL ? ['--connect', process.env.VITE_FELTDB_URL] : []),
         ...(open ? [] : ['--no-open']),
     ]);
 }
+function runLocalVite(args, waitForExit) {
+    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(executable, ['exec', '--', 'vite', ...args], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (!waitForExit)
+        return child;
+    return new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Vite exited with status ${code ?? 'unknown'}`)));
+    });
+}
 async function handleBuild(args) {
     console.log('🔨 Building FeltDB application...\n');
     const configPath = path.join(process.cwd(), 'feltdb.config.json');
@@ -897,11 +1012,13 @@ async function handleStudio(args) {
     const require = createRequire(import.meta.url);
     const packageFile = require.resolve('@feltdb/core/package.json');
     const root = path.join(path.dirname(packageFile), 'dist', 'studio-app');
+    if (!fs.existsSync(path.join(root, 'index.html'))) {
+        console.log('⚠️  Studio application artifacts not found.');
+        return;
+    }
     const projectFlow = ['feltdb.flow', ...fs.readdirSync(process.cwd()).filter(value => value.endsWith('.flow'))]
         .map(value => path.resolve(process.cwd(), value))
         .find((value, index, values) => values.indexOf(value) === index && fs.existsSync(value));
-    if (!fs.existsSync(path.join(root, 'index.html')))
-        throw new Error('Studio application artifact is missing; reinstall @feltdb/core');
     const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.json': 'application/json' };
     const server = http.createServer((request, response) => {
         const pathname = decodeURIComponent(new URL(request.url || '/', 'http://localhost').pathname);
@@ -964,6 +1081,7 @@ Commands:
   connect              Connect to remote FeltDB
   status               Show connection status
   dev                  Start development server
+  investigations       List or show durable runtime investigations
   build                Build FeltDB application
   check                Validate configuration
   inspect              Inspect runtime state

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { getClient } from './api-client.js';
 import { loadFeltDBConfig, createDefaultConfig, validateModel, } from './config.js';
-const VERSION = '0.6.9';
+const VERSION = '0.6.10';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/collection.d.ts

@@ -8,9 +8,27 @@
  * for efficient, real-time state propagation.
  */
 import type { JsDb } from './feltdb.js';
-import type { IndexConfig } from './index-types.js';
+import { type FreshnessCapability, type Revision } from './freshness.js';
+import type { IndexConfig, CollectionQueryPlan } from './index-types.js';
 export type Predicate<T> = (item: T) => boolean;
 export type Subscriber<T> = (items: T[]) => void;
+/**
+ * How a refresh decided whether the local cache could be reused.
+ *
+ * Reporting only, and deliberately explicit about *why* the runtime was
+ * queried, so a benchmark or a caller can tell a validated cache hit from a
+ * fallback that happens to be fast.
+ */
+export interface FreshnessCheck {
+    /** `revision` when a revision decided it; `refresh` when the runtime was asked for the data. */
+    validation: 'revision' | 'refresh';
+    /** True only when the runtime was not queried for the collection at all. */
+    servedFromCache: boolean;
+    /** The revision the cache now corresponds to, when there is one. */
+    revision?: Revision;
+    /** Why a revision was not used. */
+    reason?: string;
+}
 /**
  * Result of an atomic version-checked update operation.
  * Represents either a successful commit or a version conflict.
@@ -49,6 +67,26 @@ export declare class Collection<T> {
     private indexBackend;
     private indexStore;
     private indexesLoaded;
+    /** Incremented whenever `cache` is replaced, so the index can tell it is stale. */
+    private cacheGeneration;
+    /** The cache generation the index entries currently reflect, or -1 for none. */
+    private indexedGeneration;
+    private lastPlan;
+    /** Cache records addressed by id, valid for `indexedGeneration`. */
+    private recordsById;
+    /** Raw payload the cache was parsed from, used to detect that nothing changed. */
+    private lastRawSnapshot;
+    /**
+     * The runtime revision the cache was built from, when the runtime offers one.
+     *
+     * Captured *before* the query that produced the cache, never after. A write
+     * landing between the two then makes this older than the data it labels,
+     * which costs one unnecessary refresh. Capturing it after would make it
+     * newer than the data, and the cache would look current forever.
+     */
+    private cachedRevision;
+    /** How the last refresh decided the cache was usable. Reporting only. */
+    private lastFreshness;
     constructor(db: JsDb, name: string, predicate?: Predicate<T>, parent?: Collection<T>, loadIndexes?: boolean);
     /**
      * Load indexes that were persisted from a previous session.
@@ -59,8 +97,46 @@ export declare class Collection<T> {
      * Returns cached results (live-updated).
      */
     all(): Promise<T[]>;
-    /** Find records whose fields match the supplied query. */
+    /**
+     * Find records whose fields match the supplied query.
+     *
+     * When a hash index covers one of the queried fields, the index supplies the
+     * candidate records and the remaining fields are checked on those candidates
+     * only. Otherwise every record is examined.
+     *
+     * The result is identical either way. The index is a projection of the same
+     * cached array a scan would walk, rebuilt whenever that array is replaced,
+     * so an indexed lookup cannot return a record a scan would miss or resolve
+     * an id the cache no longer holds.
+     *
+     * `lastQueryPlan()` reports which path ran.
+     */
     find(query?: Partial<T>): Promise<T[]>;
+    /**
+     * How the most recent `find` was answered.
+     *
+     * Exposed so an application — and the benchmark — can confirm that the index
+     * was actually consulted rather than inferring it from timing.
+     */
+    lastQueryPlan(): CollectionQueryPlan | null;
+    /** A hash index covering one of the queried fields, if there is one. */
+    private indexFor;
+    /**
+     * Candidate records from an index, or null when the index cannot be trusted.
+     *
+     * Returning null makes the caller fall back to a scan, which is always
+     * correct. That is the safe direction: a wrong answer is far worse than a
+     * slow one.
+     */
+    private indexCandidates;
+    /**
+     * Rebuild the index from the current cache when the cache has moved on.
+     *
+     * The index is only ever a projection of `this.cache`. Deriving it from the
+     * same array a scan walks is what makes the two paths agree by construction,
+     * rather than by hoping every write path remembered to update the index.
+     */
+    private ensureIndexReflectsCache;
     /**
      * Create an index on this collection for faster queries.
      * @example
@@ -159,6 +235,38 @@ export declare class Collection<T> {
     subscribe(subscriber: Subscriber<T>, _pollInterval?: number): () => void;
     /** Release runtime subscriptions owned by this live collection. */
     close(): void;
+    /**
+     * What this collection's runtime can tell it about staleness.
+     *
+     * This is a *validation mechanism*, not a guarantee that the cache is fresh.
+     * `validation: 'revision'` means a cheap staleness check exists; it says
+     * nothing about whether this collection's cache currently passes it.
+     *
+     * @example
+     * const capability = await people.freshness();
+     * // 'revision' -> a cheap staleness check exists
+     * // 'refresh'  -> re-read is the only honest answer, and `reason` says why
+     */
+    freshness(): Promise<FreshnessCapability>;
+    /**
+     * How the last refresh decided the cache was usable.
+     *
+     * `servedFromCache` is true only when the runtime was never asked for this
+     * collection's data. Reporting only; it exists so a benchmark can tell a
+     * validated cache hit from a fallback that merely happened to be fast.
+     */
+    lastFreshnessCheck(): FreshnessCheck | null;
+    /**
+     * Read the runtime's current revision, or explain why there isn't one.
+     *
+     * The capability is re-checked on every call rather than remembered, because
+     * a deployment can change underneath a live collection: switching on
+     * replication revokes revision authority, and a collection holding a cached
+     * capability would keep trusting a number that stopped meaning anything.
+     * Any refusal — no capability, a topology change, a transport failure —
+     * lands here as a reason, and the caller falls back to a full refresh.
+     */
+    private currentRevision;
     /**
      * Refresh data from the database and notify subscribers.
      */

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAc,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAErF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;AAChD,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,mFAAmF;IACnF,OAAO,CAAC,eAAe,CAAK;IAC5B,gFAAgF;IAChF,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAoC;IACpD,oEAAoE;IACpE,OAAO,CAAC,WAAW,CAA+B;IAClD,kFAAkF;IAClF,OAAO,CAAC,eAAe,CAAuB;IAC9C;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc,CAAyB;IAC/C,yEAAyE;IACzE,OAAO,CAAC,aAAa,CAA+B;gBAExC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,UAAO;IAoBxG;;OAEG;YACW,oBAAoB;IAalC;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAKzB;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,KAAK,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAsChD;;;;;OAKG;IACH,aAAa,IAAI,mBAAmB,GAAG,IAAI;IAI3C,wEAAwE;IACxE,OAAO,CAAC,QAAQ;IAWhB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAiBvB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAWtC;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE;IAI5B;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAazC;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAYjD;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAO7C;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BrE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,eAAe,CACnB,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,aAAa,CAAC,EAAE,MAAM,EACtB,eAAe,CAAC,EAAE,MAAM,EACxB,gBAAgB,CAAC,EAAE,OAAO,EAC1B,YAAY,CAAC,EAAE,CAAC,GACf,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IAmEpC;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD;;;;;;OAMG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAmClG;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI;IA6CxE,mEAAmE;IACnE,KAAK,IAAI,IAAI;IASb;;;;;;;;;;;OAWG;IACH,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAIzC;;;;;;OAMG;IACH,kBAAkB,IAAI,cAAc,GAAG,IAAI;IAI3C;;;;;;;;;OASG;YACW,eAAe;IAQ7B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA2E/B;AAED;;GAEG;AACH,qBAAa,YAAY,CAAC,MAAM,EAAE,KAAK;IACrC,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,UAAU,CAAoC;gBAGpD,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,IAAI,EACb,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,MAAM;IAQ/C;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAoBxD"}