@feltdb/core 0.11.7 → 0.11.8

package/dist/file-db.js

@@ -6,6 +6,31 @@ import { decideTransaction, embeddedResult, EmbeddedTransactionRejected, } from
 import { EmbeddedQueryEngine } from './embedded-query.js';
 import { encodeRecord, scanJournal, JournalCorruptionError, PersistenceProfiler, } from './file-journal.js';
 export { JournalCorruptionError } from './file-journal.js';
+/** The newest local file snapshot format this build reads and writes. */
+export const FILE_SNAPSHOT_FORMAT_VERSION = 2;
+/**
+ * The runtime directory was written in a durable format newer than this build
+ * understands.
+ *
+ * Refused rather than recovered around: treating a newer snapshot as invalid
+ * and falling back to an older backup — or to an empty database — silently
+ * discards every commit the newer format carries. That is exactly what a
+ * package-only rollback onto upgraded data would do, so it fails closed.
+ */
+export class UnsupportedDurableFormatError extends Error {
+    statePath;
+    found;
+    code = 'UNSUPPORTED_DURABLE_FORMAT';
+    constructor(statePath, found) {
+        super(`UNSUPPORTED_DURABLE_FORMAT: ${statePath} is in local durable format ${found}; this FeltDB `
+            + `build reads formats 1-${FILE_SNAPSHOT_FORMAT_VERSION}. It was written by a newer FeltDB. `
+            + 'The database was not opened and was not modified. Upgrade FeltDB, or restore the backup '
+            + 'taken before the upgrade.');
+        this.statePath = statePath;
+        this.found = found;
+        this.name = 'UnsupportedDurableFormatError';
+    }
+}
 // Synchronous versions for sync API (will throw if called in browser)
 function getFsSync() {
     if (typeof nodeFs.existsSync === 'function')
@@ -98,6 +123,9 @@ export class FileJsDb {
     parseSnapshot(path) {
         const content = getFsSync().readFileSync(path, 'utf-8');
         const snapshot = JSON.parse(content);
+        if (typeof snapshot.version === 'number' && snapshot.version > FILE_SNAPSHOT_FORMAT_VERSION) {
+            throw new UnsupportedDurableFormatError(path, snapshot.version);
+        }
         const known = snapshot.version === 1
             || (snapshot.version === 2 && Number.isInteger(snapshot.journal?.generation) && Number.isInteger(snapshot.journal?.commit));
         if (!known || !snapshot.meta || !snapshot.rows || !snapshot.events)
@@ -119,6 +147,8 @@ export class FileJsDb {
                 console.warn(`Invalid snapshot structure at ${this.statePath}, attempting backup recovery`);
             }
             catch (error) {
+                if (error instanceof UnsupportedDurableFormatError)
+                    throw error;
                 if (!isMissing(error)) {
                     console.warn(`Failed to load snapshot from ${this.statePath}: ${error}`);
                     console.warn(`Attempting to recover from backup...`);
@@ -134,7 +164,9 @@ export class FileJsDb {
                     return { snapshot: parsed.snapshot, bytes: parsed.bytes, source: 'backup' };
                 }
             }
-            catch {
+            catch (error) {
+                if (error instanceof UnsupportedDurableFormatError)
+                    throw error;
                 // Backup is also corrupted or invalid
             }
             console.warn(`Backup recovery failed, reinitializing state`);
@@ -553,7 +585,7 @@ export class FileJsDb {
         this.syncDirectory();
         this.state.peers = [...this.peers];
         const snapshot = {
-            version: 2,
+            version: FILE_SNAPSHOT_FORMAT_VERSION,
             timestamp: Date.now(),
             meta: {
                 instance_id: this.origin,

package/dist/runtime-snapshot.d.ts

@@ -132,6 +132,44 @@ export interface SnapshotStaleness {
     /** Why currency could not be decided. */
     reason?: string;
 }
+/**
+ * Which authoritative state a published snapshot represents, stated explicitly.
+ *
+ * Two snapshots with the same `id` represent the same durable state, derived
+ * by the same definition, under the same authority. The identity is computed
+ * from what the snapshot already is — its revision, definition, and authority
+ * — rather than stored as parallel metadata that could disagree with it.
+ */
+export interface SnapshotIdentity {
+    /** `snap_` + SHA-256 over the fields below. Deterministic across handles and processes. */
+    id: string;
+    name: string;
+    /**
+     * The authoritative revision value, when the runtime has one. `null` when it
+     * does not, in which case `contentDigest` identifies the state instead.
+     */
+    version: number | null;
+    /** The revision's consistency domain, when there is a revision. */
+    scope?: string;
+    /** Publication counter of the handle. Informational; not part of `id`. */
+    generation: number;
+    /** The source collections, sorted. */
+    sourceSet: readonly string[];
+    /** SHA-256 of the definition's sources, filters, and indexes. */
+    definitionDigest: string;
+    /** The authority the materialization read under (`tenant/…`, `platform`, or `unscoped`). */
+    authorityContext: string;
+    /**
+     * SHA-256 of the canonical materialized records. Present only when no
+     * authoritative revision exists, because then the content is the only honest
+     * identity there is.
+     */
+    contentDigest?: string;
+    /** How `id` was derived. */
+    derivation: 'revision' | 'content';
+    /** When materialization completed. Reporting only; not part of `id`. */
+    createdAt: number;
+}
 export interface SnapshotIndexDescription {
     collection: string;
     name: string;
@@ -175,6 +213,14 @@ export interface SnapshotHandleExplanation extends SnapshotExplanation {
      * claim.
      */
     durableReads: number;
+    /**
+     * `refresh()` calls answered by the fast path: the active snapshot already
+     * represented the current authoritative revision, so nothing was read or
+     * rebuilt.
+     */
+    reused: number;
+    /** The authority the handle materializes under. */
+    authorityContext: string;
 }
 export declare class SnapshotDefinitionError extends Error {
     constructor(message: string);
@@ -209,6 +255,11 @@ export interface RuntimeSnapshot<D = undefined> {
     /** Materialized records, across every source. */
     readonly records: number;
     readonly collections: readonly string[];
+    /**
+     * Which authoritative state this snapshot represents. Computed on first
+     * access and memoized, so the hot read path never pays for it.
+     */
+    readonly identity: SnapshotIdentity;
     get<T = Record<string, unknown>>(collection: string, id: string | number): T | undefined;
     has(collection: string, id: string | number): boolean;
     /** Every materialized record of one collection, in materialization order. Frozen. */
@@ -231,6 +282,17 @@ export interface RuntimeSnapshot<D = undefined> {
 export interface SnapshotSourceRuntime {
     /** Read every authoritative record of one collection. */
     readRecords(collection: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Read only the authoritative records that satisfy `where`, through the
+     * runtime's own bounded query (and its indexes, where it has them).
+     *
+     * Optional. When present it is the bounded source-selection fast path: a
+     * snapshot that selects ten records of a large collection reads ten records,
+     * not the collection. It must return exactly the records `readRecords` would
+     * after filtering by the same conditions — the build re-applies the filter
+     * regardless, so a runtime that over-returns cannot widen a snapshot.
+     */
+    readSelected?(collection: string, where: SnapshotCondition[]): Promise<Array<Record<string, unknown>>>;
     /** What freshness validation the underlying runtime can honestly support. */
     freshness(): Promise<FreshnessCapability>;
     /** The runtime's current revision. Called only when freshness advertises one. */
@@ -254,7 +316,10 @@ export declare class RuntimeSnapshotHandle<D = undefined> {
     private durableReads;
     private lastFailure?;
     private closed;
-    constructor(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime);
+    private reused;
+    private readonly definitionDigest;
+    readonly authorityContext: string;
+    constructor(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime, options?: RuntimeSnapshotOptions);
     get name(): string;
     /**
      * The active snapshot, or `undefined` before the first successful build.
@@ -325,7 +390,16 @@ export declare function assertSnapshotDefinition(definition: SnapshotDefinition<
  * `StateFirstDB.snapshot()` is the application-facing form; this is the same
  * primitive for runtimes and tools that hold a source of their own.
  */
-export declare function createRuntimeSnapshot<D = undefined>(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime): RuntimeSnapshotHandle<D>;
+export declare function createRuntimeSnapshot<D = undefined>(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime, options?: RuntimeSnapshotOptions): RuntimeSnapshotHandle<D>;
+export interface RuntimeSnapshotOptions {
+    /**
+     * The authority the source reads under. `db.snapshot()` supplies the
+     * database's own authority scope; the source it hands the handle is already
+     * bound to that scope, so a snapshot can never read more than its database
+     * could. Recorded in every snapshot's identity.
+     */
+    authorityContext?: string;
+}
 /**
  * Whether two definitions describe the same snapshot.
  *

package/dist/runtime-snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-snapshot.d.ts","sourceRoot":"","sources":["../src/runtime-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAyC,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AACzD,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;AACnF,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpF,wFAAwF;AACxF,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACpE;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,SAAS;IAC/C,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,2BAA2B,KAAK,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,mGAAmG;IACnG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,SAAS,EAAE,QAAQ,GAAG,UAAU,CAAC;IACjC,gFAAgF;IAChF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,OAAO,EAAE,wBAAwB,EAAE,CAAC;CACrC;AAED,8DAA8D;AAC9D,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAC5B;AAED,iFAAiF;AACjF,qBAAa,kBAAmB,SAAQ,KAAK;IACd,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CACtD;AAED,yDAAyD;AACzD,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAC5B;AAED,wEAAwE;AACxE,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,SAAS;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IACzF,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACtD,qFAAqF;IACrF,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IACnE,gFAAgF;IAChF,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;IACxF,kEAAkE;IAClE,OAAO,IAAI,CAAC,CAAC;IACb,sEAAsE;IACtE,OAAO,IAAI,mBAAmB,CAAC;IAC/B,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,wBAAwB,CAAC;CAClE;AAqFD;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,6EAA6E;IAC7E,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC1C,iFAAiF;IACjF,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB,CAAC,CAAC,GAAG,SAAS;IAY5C,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,OAAO,CAAC,MAAM,CAAC,CAAuB;IACtC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,CAA8B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqD;IAC/E,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAC,CAAkC;IACtD,OAAO,CAAC,MAAM,CAAS;gBAGZ,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,qBAAqB;IAKhD,IAAI,IAAI,IAAI,MAAM,CAAiC;IAEnD;;;;OAIG;IACH,IAAI,OAAO,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAwB;IAErE,iFAAiF;IACjF,IAAI,IAAI,eAAe,CAAC,CAAC,CAAC;IAS1B;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAS7E;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAkB1C,0EAA0E;IACpE,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAyB7C,mFAAmF;IACnF,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKvE,6EAA6E;IAC7E,OAAO,IAAI,yBAAyB;IAsBpC;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,UAAU;IAIlB;;;OAGG;IACH,OAAO,CAAC,KAAK;YASC,QAAQ;YA0CR,WAAW;IAyEzB;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;CAchB;AAOD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,kBAAkB,CAAC,GAAG,CAAC,GAAG,IAAI,CAgDlF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,SAAS,EACjD,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,EACjC,MAAM,EAAE,qBAAqB,GAC5B,qBAAqB,CAAC,CAAC,CAAC,CAE1B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,GAAG,CAAC,GAAG,OAAO,CAc/G"}
+{"version":3,"file":"runtime-snapshot.d.ts","sourceRoot":"","sources":["../src/runtime-snapshot.ts"],"names":[],"mappings":"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"}

package/dist/runtime-snapshot.js

@@ -30,6 +30,7 @@
  */
 import { isCacheCurrent, } from './freshness.js';
 import { conditionMatches, EmbeddedQueryEngine } from './embedded-query.js';
+import { canonicalJson, sha256Hex } from './stable-hash.js';
 export class SnapshotDefinitionError extends Error {
     constructor(message) { super(message); this.name = 'SnapshotDefinitionError'; }
 }
@@ -56,17 +57,57 @@ class PublishedSnapshot {
     generation;
     basis;
     materialization;
+    definitionDigest;
+    authorityContext;
     collections;
     records;
-    constructor(name, generation, basis, materialization) {
+    // Memo cell, not snapshot state: identity is a pure function of what is
+    // already frozen, computed once on first access.
+    memo = {};
+    constructor(name, generation, basis, materialization, definitionDigest, authorityContext) {
         this.name = name;
         this.generation = generation;
         this.basis = basis;
         this.materialization = materialization;
+        this.definitionDigest = definitionDigest;
+        this.authorityContext = authorityContext;
         this.collections = Object.freeze([...materialization.byCollection.keys()]);
         this.records = materialization.records.size;
         Object.freeze(this);
     }
+    get identity() {
+        if (this.memo.identity)
+            return this.memo.identity;
+        const sourceSet = Object.freeze([...this.collections].sort());
+        const revision = this.basis.validation === 'revision' ? this.basis.revision : undefined;
+        const contentDigest = revision ? undefined : sha256Hex(canonicalJson(sourceSet.map(collection => [
+            collection,
+            [...(this.materialization.byCollection.get(collection) ?? EMPTY)]
+                .map(record => canonicalJson(record))
+                .sort(),
+        ])));
+        const id = `snap_${sha256Hex(canonicalJson([
+            'feltdb.snapshot.v1',
+            this.name,
+            this.definitionDigest,
+            this.authorityContext,
+            revision ? ['revision', revision.scope, revision.value] : ['content', contentDigest],
+        ]))}`;
+        this.memo.identity = Object.freeze({
+            id,
+            name: this.name,
+            version: revision ? revision.value : null,
+            ...(revision ? { scope: revision.scope } : {}),
+            generation: this.generation,
+            sourceSet,
+            definitionDigest: this.definitionDigest,
+            authorityContext: this.authorityContext,
+            ...(contentDigest ? { contentDigest } : {}),
+            derivation: revision ? 'revision' : 'content',
+            createdAt: this.basis.materializedAt,
+        });
+        return this.memo.identity;
+    }
     get revision() { return this.basis.revision; }
     get materializedAt() { return this.basis.materializedAt; }
     get(collection, id) {
@@ -129,10 +170,15 @@ export class RuntimeSnapshotHandle {
     durableReads = 0;
     lastFailure;
     closed = false;
-    constructor(definition, source) {
+    reused = 0;
+    definitionDigest;
+    authorityContext;
+    constructor(definition, source, options = {}) {
         this.definition = definition;
         this.source = source;
         assertSnapshotDefinition(definition);
+        this.definitionDigest = sha256Hex(definitionShape(definition));
+        this.authorityContext = options.authorityContext ?? 'unscoped';
     }
     get name() { return this.definition.name; }
     /**
@@ -162,8 +208,10 @@ export class RuntimeSnapshotHandle {
         this.assertOpen();
         if (!options.force && this.active) {
             const staleness = await this.staleness();
-            if (staleness.state === 'current')
+            if (staleness.state === 'current') {
+                this.reused += 1;
                 return this.active;
+            }
         }
         return this.build();
     }
@@ -240,6 +288,8 @@ export class RuntimeSnapshotHandle {
             failures: this.failures,
             ...(this.lastFailure ? { lastFailure: this.lastFailure } : {}),
             durableReads: this.durableReads,
+            reused: this.reused,
+            authorityContext: this.authorityContext,
         };
     }
     /**
@@ -322,7 +372,9 @@ export class RuntimeSnapshotHandle {
         const indexes = [];
         for (const source of this.definition.sources) {
             this.durableReads += 1;
-            const durable = await this.source.readRecords(source.collection);
+            const durable = source.where?.length && this.source.readSelected
+                ? await this.source.readSelected(source.collection, source.where)
+                : await this.source.readRecords(source.collection);
             const kept = [];
             for (const record of durable) {
                 if (!record || typeof record !== 'object' || Array.isArray(record))
@@ -389,7 +441,7 @@ export class RuntimeSnapshotHandle {
      * visible.
      */
     publish(materialization, basis) {
-        const candidate = new PublishedSnapshot(this.name, this.generation + 1, Object.freeze(basis), materialization);
+        const candidate = new PublishedSnapshot(this.name, this.generation + 1, Object.freeze(basis), materialization, this.definitionDigest, this.authorityContext);
         this.definition.validate?.(candidate);
         this.active = candidate;
         this.generation = candidate.generation;
@@ -455,8 +507,17 @@ export function assertSnapshotDefinition(definition) {
  * `StateFirstDB.snapshot()` is the application-facing form; this is the same
  * primitive for runtimes and tools that hold a source of their own.
  */
-export function createRuntimeSnapshot(definition, source) {
-    return new RuntimeSnapshotHandle(definition, source);
+export function createRuntimeSnapshot(definition, source, options = {}) {
+    return new RuntimeSnapshotHandle(definition, source, options);
+}
+/** The identity-bearing shape of a definition: sources, filters, and indexes. */
+function definitionShape(definition) {
+    return canonicalJson({
+        name: definition.name,
+        sources: [...definition.sources]
+            .map(source => ({ collection: source.collection, where: source.where ?? [], indexes: source.indexes ?? [] }))
+            .sort((left, right) => (left.collection < right.collection ? -1 : left.collection > right.collection ? 1 : 0)),
+    });
 }
 /**
  * Whether two definitions describe the same snapshot.

package/dist/stable-hash.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Synchronous, dependency-free SHA-256 and canonical JSON.
+ *
+ * Snapshot identity must be computable in every runtime `@feltdb/core` ships
+ * to — Node, browsers, workers — and synchronously, because a published
+ * snapshot answers without awaiting anything. WebCrypto is asynchronous and
+ * `node:crypto` is not available in a browser, so this is the small portable
+ * implementation both need. It is used for identity, not for security.
+ */
+/** SHA-256 of a UTF-8 string, as lowercase hex. */
+export declare function sha256Hex(input: string): string;
+/**
+ * JSON with object keys sorted at every depth, so two structurally equal
+ * values serialize to the same bytes regardless of insertion order.
+ */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=stable-hash.d.ts.map

package/dist/stable-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-hash.d.ts","sourceRoot":"","sources":["../src/stable-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA+B/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUpD"}

package/dist/stable-hash.js

@@ -0,0 +1,82 @@
+/**
+ * Synchronous, dependency-free SHA-256 and canonical JSON.
+ *
+ * Snapshot identity must be computable in every runtime `@feltdb/core` ships
+ * to — Node, browsers, workers — and synchronously, because a published
+ * snapshot answers without awaiting anything. WebCrypto is asynchronous and
+ * `node:crypto` is not available in a browser, so this is the small portable
+ * implementation both need. It is used for identity, not for security.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** SHA-256 of a UTF-8 string, as lowercase hex. */
+export function sha256Hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    const bitLength = bytes.length * 8;
+    const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(padded.length - 4, bitLength >>> 0);
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i += 1)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i += 1) {
+            const a = w[i - 15], b = w[i - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const t1 = (hh + s1 + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+            const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const t2 = (s0 + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] += a;
+        h[1] += b;
+        h[2] += c;
+        h[3] += d;
+        h[4] += e;
+        h[5] += f;
+        h[6] += g;
+        h[7] += hh;
+    }
+    return Array.from(h, word => word.toString(16).padStart(8, '0')).join('');
+}
+/**
+ * JSON with object keys sorted at every depth, so two structurally equal
+ * values serialize to the same bytes regardless of insertion order.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return value === undefined ? 'null' : JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.keys(value)
+        .filter(key => value[key] !== undefined)
+        .sort()
+        .map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+    return `{${entries.join(',')}}`;
+}