@feltdb/core 0.6.9 → 0.6.11

package/dist/collection.js

@@ -7,6 +7,7 @@
  * Collections now use reactive dependency graphs instead of polling
  * for efficient, real-time state propagation.
  */
+import { describeFreshness, isCacheCurrent, readRevision, } from './freshness.js';
 import { getReactiveDependencyGraph } from './reactive-graph.js';
 import { IndexBackend } from './index-backend.js';
 import { IndexStore } from './index-store.js';
@@ -29,6 +30,26 @@ export class Collection {
         this.runtimeUnsubscribe = null;
         this.indexBackend = new IndexBackend();
         this.indexesLoaded = false;
+        /** Incremented whenever `cache` is replaced, so the index can tell it is stale. */
+        this.cacheGeneration = 0;
+        /** The cache generation the index entries currently reflect, or -1 for none. */
+        this.indexedGeneration = -1;
+        this.lastPlan = null;
+        /** Cache records addressed by id, valid for `indexedGeneration`. */
+        this.recordsById = null;
+        /** Raw payload the cache was parsed from, used to detect that nothing changed. */
+        this.lastRawSnapshot = null;
+        /**
+         * 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.
+         */
+        this.cachedRevision = null;
+        /** How the last refresh decided the cache was usable. Reporting only. */
+        this.lastFreshness = null;
         this.db = db;
         this.name = name;
         this.collectionId = `${name}-${Math.random().toString(36).substr(2, 9)}`;
@@ -71,11 +92,132 @@ export class Collection {
         await this.refresh();
         return [...this.cache];
     }
-    /** 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.
+     */
     async find(query = {}) {
         const items = await this.all();
         const entries = Object.entries(query);
-        return items.filter((item) => entries.every(([field, expected]) => item[field] === expected));
+        if (entries.length === 0) {
+            this.lastPlan = { strategy: 'scan', reason: 'no query fields', candidatesExamined: items.length, recordsReturned: items.length };
+            return items;
+        }
+        const matches = (item) => entries.every(([field, expected]) => item[field] === expected);
+        const usable = this.indexFor(entries);
+        if (usable) {
+            const candidates = this.indexCandidates(usable.indexName, usable.field, usable.value);
+            if (candidates) {
+                const found = candidates.filter(matches);
+                this.lastPlan = {
+                    strategy: 'index',
+                    indexName: usable.indexName,
+                    field: usable.field,
+                    candidatesExamined: candidates.length,
+                    recordsReturned: found.length,
+                };
+                return found;
+            }
+        }
+        const found = items.filter(matches);
+        this.lastPlan = {
+            strategy: 'scan',
+            reason: usable ? 'index could not be trusted for this snapshot' : 'no index covers the queried fields',
+            candidatesExamined: items.length,
+            recordsReturned: found.length,
+        };
+        return found;
+    }
+    /**
+     * 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() {
+        return this.lastPlan;
+    }
+    /** A hash index covering one of the queried fields, if there is one. */
+    indexFor(entries) {
+        for (const config of this.indexBackend.listIndexes()) {
+            // Only equality on a single-field hash index is planned today. Sorted,
+            // compound, and text indexes are maintained but not yet used for reads.
+            if (config.type !== 'hash' || !config.field)
+                continue;
+            const entry = entries.find(([field]) => field === config.field);
+            if (entry)
+                return { indexName: config.name, field: config.field, value: entry[1] };
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    indexCandidates(indexName, field, value) {
+        if (!this.ensureIndexReflectsCache())
+            return null;
+        let ids;
+        try {
+            ids = this.indexBackend.queryIndex(indexName, { field, operator: 'eq', value });
+        }
+        catch {
+            return null;
+        }
+        const records = [];
+        for (const id of ids) {
+            const record = this.recordsById?.get(id);
+            if (record === undefined)
+                return null; // the index disagrees with the cache
+            records.push(record);
+        }
+        return records;
+    }
+    /**
+     * 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.
+     */
+    ensureIndexReflectsCache() {
+        if (this.indexedGeneration === this.cacheGeneration)
+            return this.recordsById !== null;
+        if (!this.indexBackend.resetEntries()) {
+            this.recordsById = null;
+            return false;
+        }
+        const byId = new Map();
+        for (const item of this.cache) {
+            const recordId = item?.id;
+            // A record without a stable id cannot be resolved from an index result,
+            // so the whole snapshot is treated as unindexable rather than partially
+            // indexed.
+            if (recordId === undefined || recordId === null) {
+                this.recordsById = null;
+                this.indexedGeneration = this.cacheGeneration;
+                return false;
+            }
+            const key = String(recordId);
+            byId.set(key, item);
+            this.indexBackend.updateRecord(key, null, item);
+        }
+        this.recordsById = byId;
+        this.indexedGeneration = this.cacheGeneration;
+        return true;
     }
     /**
      * Create an index on this collection for faster queries.
@@ -424,13 +566,93 @@ export class Collection {
             unsubscribe();
         this.unsubscribeFunctions.clear();
     }
+    /**
+     * 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() {
+        return describeFreshness(this.db);
+    }
+    /**
+     * 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() {
+        return this.lastFreshness;
+    }
+    /**
+     * 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.
+     */
+    async currentRevision() {
+        try {
+            return { revision: await readRevision(this.db) };
+        }
+        catch (error) {
+            return { reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
     /**
      * Refresh data from the database and notify subscribers.
      */
     async refresh() {
         try {
+            // The revision is read *before* the query, so it can only ever be older
+            // than the data it ends up labelling. The reverse ordering would let a
+            // write that lands between the query and the revision read produce a
+            // cache tagged with a revision it does not contain, and that cache would
+            // then validate as current forever.
+            const observed = await this.currentRevision();
+            if ('revision' in observed) {
+                if (this.isInitialized && this.cachedRevision
+                    && isCacheCurrent(this.cachedRevision, observed.revision)) {
+                    // The runtime is not queried at all. This is the only path in this
+                    // method that skips the round trip, and it is reachable only when
+                    // the runtime advertised an authoritative revision for its domain.
+                    this.lastFreshness = { validation: 'revision', servedFromCache: true, revision: observed.revision };
+                    return;
+                }
+            }
+            else {
+                // No usable revision: the existing behaviour, unchanged.
+                this.cachedRevision = null;
+            }
             const result = await this.db.query(this.name);
+            this.lastFreshness = 'revision' in observed
+                ? { validation: 'revision', servedFromCache: false, revision: observed.revision }
+                : { validation: 'refresh', servedFromCache: false, reason: observed.reason };
             if (result.success && result.data) {
+                // Record the revision only once the data it labels is actually in
+                // hand. A failed query must not leave the cache tagged as current.
+                this.cachedRevision = 'revision' in observed ? observed.revision : null;
+                // The runtime returned exactly what it returned last time, so the data
+                // has not changed. Re-parsing it would produce an identical array,
+                // discard the cache, and invalidate any index derived from it — paying
+                // twice to learn nothing.
+                //
+                // This remains useful for runtimes with no revision, and as a second
+                // line for those that have one: it is what keeps the index valid when
+                // some *other* collection's write moved a store-wide revision.
+                if (this.isInitialized && result.data === this.lastRawSnapshot) {
+                    return;
+                }
                 try {
                     let items = JSON.parse(result.data);
                     // Apply predicate if this is a derived collection
@@ -444,8 +666,11 @@ export class Collection {
                             }
                         });
                     }
-                    // Update cache with all results
+                    // Update cache with all results. The index is a projection of this
+                    // array, so replacing it invalidates the index entries.
                     this.cache = items;
+                    this.cacheGeneration += 1;
+                    this.lastRawSnapshot = result.data;
                     this.isInitialized = true;
                 }
                 catch (err) {

package/dist/create/cli.js

@@ -345,17 +345,19 @@ Learn more: https://github.com/rkendel1/feltdb`);
                     console.log('Build the production application image with: docker compose build app');
                 }
                 else {
-                    console.log('\n🚀 Starting the application and FeltDB Studio...\n');
+                    console.log('\n🚀 Starting the application...\n');
                     await run(npm, ['run', 'dev'], projectDir);
                 }
             }
         }
         else {
-            console.log('Project is ready. Start everything with:');
+            console.log('Project is ready. Start the application with:');
             console.log(`  cd ${projectName}`);
             if (!shouldInstall)
                 console.log('  npm install');
             console.log('  npm run dev');
+            console.log('Start FeltDB development tooling separately with:');
+            console.log('  npm run feltdb:dev');
         }
     }
     catch (error) {

package/dist/create/create.js

@@ -7,6 +7,7 @@ import { randomBytes } from 'crypto';
 import { feltdbPackageRange } from './package-versions.js';
 import { generateDockerCompose, generateDockerfile, generateDockerIgnore, generateDotEnvLocal, generateFeltDBDockerfile, generateStudioDockerfile, } from './docker-compose-generator.js';
 import { initializeWorkspace, appendWorkspaceGitignore, } from './workspace-initialization.js';
+import { frameworkScaffold } from './frameworks.js';
 export async function createProject(options) {
     const { projectName, templatesDir } = options;
     const projectDir = path.resolve(process.cwd(), projectName);
@@ -29,6 +30,7 @@ export async function createProject(options) {
     fs.mkdirSync(feltdbConfigDir, { recursive: true });
     const runtime = options.runtime || 'browser';
     const framework = options.framework || 'react';
+    const applicationFramework = frameworkScaffold(framework);
     const distributed = options.distributed !== false;
     const hasAgents = options.agents !== false;
     const hasWebLLM = options.webllm !== false;
@@ -41,7 +43,8 @@ export async function createProject(options) {
         main: 'src/index.ts',
         type: 'module',
         scripts: {
-            dev: 'feltdb dev',
+            dev: applicationFramework.applicationDevCommand,
+            'feltdb:dev': 'feltdb dev',
             build: 'feltdb build',
             test: 'node --test',
             feltdb: 'feltdb',
@@ -81,6 +84,10 @@ export async function createProject(options) {
         agents: {
             enabled: hasAgents,
         },
+        application: {
+            lifecycle: 'managed',
+        },
+        applicationUrl: 'http://127.0.0.1:5173',
         capabilities: {},
     };
     if (capabilities.includes('search')) {
@@ -185,13 +192,23 @@ ${hasAgents ? `  agent WorkspaceAssistant {
     fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
     // Create main application files
     const runtimeOptions = runtime === 'browser'
-        ? "{ namespace: '" + applicationName + "', browser: true }"
+        ? "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', browser: true }"
         : runtime === 'managed'
-            ? "{ namespace: import.meta.env.VITE_FELTDB_MANAGED_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_MANAGED_URL || import.meta.env.VITE_FELTDB_URL || '', token: import.meta.env.VITE_FELTDB_MANAGED_API_KEY || import.meta.env.VITE_FELTDB_API_KEY || '' } }"
+            ? "{ namespace: import.meta.env.VITE_FELTDB_MANAGED_NAMESPACE || import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_MANAGED_URL || import.meta.env.VITE_FELTDB_URL || '', token: import.meta.env.VITE_FELTDB_MANAGED_API_KEY || import.meta.env.VITE_FELTDB_API_KEY || '' } }"
             : runtime === 'self-hosted'
-                ? "{ namespace: '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
-                : "{ namespace: '" + applicationName + "', memory: true }";
-    const feltdbTs = `import { createFeltDB } from '@feltdb/core';
+                ? "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
+                : "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', memory: true }";
+    const feltdbTs = `import { configureDevelopmentRuntimeBridge, createFeltDB } from '@feltdb/core';
+
+configureDevelopmentRuntimeBridge({
+  sessionId: import.meta.env.VITE_FELTDB_DEV_SESSION_ID,
+  workspaceId: import.meta.env.VITE_FELTDB_WORKSPACE_ID,
+  namespace: import.meta.env.VITE_FELTDB_NAMESPACE,
+  runtime: import.meta.env.VITE_FELTDB_RUNTIME,
+  authorityUrl: import.meta.env.VITE_FELTDB_AUTHORITY_URL,
+  bridgeUrl: import.meta.env.VITE_FELTDB_DEV_BRIDGE_URL,
+  applicationUrl: import.meta.env.VITE_FELTDB_APPLICATION_URL,
+});
 
 export const db = createFeltDB(${runtimeOptions});
 
@@ -1523,6 +1540,8 @@ A FeltDB Workspace application demonstrating local-first database capabilities.
 
 ## Quick Start
 
+Start the application:
+
 \`\`\`bash
 npm install
 npm run dev
@@ -1530,6 +1549,13 @@ npm run dev
 
 The application will be available at http://localhost:5173 (or your configured port).
 
+In a second terminal, start FeltDB authority, pairing, and Studio and attach it
+to the application explicitly:
+
+\`\`\`bash
+npm run feltdb:dev
+\`\`\`
+
 ## FeltDB Workspace Showcase
 
 This application demonstrates core FeltDB capabilities:
@@ -1628,6 +1654,10 @@ Configuration is in \`feltdb.config.json\`:
   "agents": {
     "enabled": ${hasAgents}
   },
+  "application": {
+    "lifecycle": "managed"
+  },
+  "applicationUrl": "http://127.0.0.1:5173",
   "capabilities": ["${capabilities}"]
 }
 \`\`\`
@@ -1653,6 +1683,12 @@ These are required when connecting to an authenticated self-hosted or managed Fe
 npm run dev
 \`\`\`
 
+### Start FeltDB Development Tooling
+
+\`\`\`bash
+npm run feltdb:dev
+\`\`\`
+
 ### Build for Production
 \`\`\`bash
 npm run build

package/dist/create/frameworks.js

@@ -0,0 +1,18 @@
+const FRAMEWORK_SCAFFOLDS = {
+    react: {
+        name: 'react',
+        applicationDevCommand: 'vite',
+    },
+    vanilla: {
+        name: 'vanilla',
+        applicationDevCommand: 'vite',
+    },
+};
+/** Resolve framework-owned application lifecycle metadata. */
+export function frameworkScaffold(framework) {
+    const scaffold = FRAMEWORK_SCAFFOLDS[framework];
+    if (!scaffold) {
+        throw new Error(`Unsupported framework "${framework}". Choose react or vanilla.`);
+    }
+    return scaffold;
+}

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.6.9';
+export const FELTDB_PACKAGE_VERSION = '0.6.11';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;