@feltdb/core 0.11.3 → 0.11.5

package/dist/embedded-query.js

@@ -0,0 +1,327 @@
+const now = () => typeof performance !== 'undefined' ? performance.now() : Date.now();
+function compareValue(left, right) {
+    if (left === right)
+        return 0;
+    if ((left === undefined || left === null) && (right === undefined || right === null))
+        return 0;
+    if (left === undefined || left === null)
+        return -1;
+    if (right === undefined || right === null)
+        return 1;
+    if (typeof left === 'number' && typeof right === 'number')
+        return left < right ? -1 : 1;
+    return String(left).localeCompare(String(right));
+}
+function fields(config) {
+    if (config.fields?.length)
+        return config.fields.map((field, index) => ({ field, direction: config.directions?.[index] ?? 'asc' }));
+    if (config.field)
+        return [{ field: config.field, direction: config.direction ?? 'asc' }];
+    return [];
+}
+function recordId(collection, key, _record) {
+    return key.slice(collection.length + 1);
+}
+function bucketKey(value) {
+    return `${typeof value}:${JSON.stringify(value)}`;
+}
+function compareBySpecs(collection, specs, left, right) {
+    for (const spec of specs) {
+        const compared = compareValue(left.record[spec.field], right.record[spec.field]);
+        if (compared)
+            return spec.direction === 'asc' ? compared : -compared;
+    }
+    return recordId(collection, left.key, left.record).localeCompare(recordId(collection, right.key, right.record));
+}
+function conditionMatches(record, condition) {
+    const actual = record[condition.field];
+    if ('eq' in condition && actual !== condition.eq)
+        return false;
+    if ('neq' in condition && actual === condition.neq)
+        return false;
+    if ('lt' in condition && compareValue(actual, condition.lt) >= 0)
+        return false;
+    if ('lte' in condition && compareValue(actual, condition.lte) > 0)
+        return false;
+    if ('gt' in condition && compareValue(actual, condition.gt) <= 0)
+        return false;
+    if ('gte' in condition && compareValue(actual, condition.gte) < 0)
+        return false;
+    return true;
+}
+function binding(query) {
+    const shape = JSON.stringify({ collection: query.collection, where: query.where ?? [], orderBy: query.orderBy ?? [], limit: query.limit });
+    let hash = 0xcbf29ce484222325n;
+    for (let index = 0; index < shape.length; index += 1) {
+        hash ^= BigInt(shape.charCodeAt(index));
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+function encode(value) {
+    const json = JSON.stringify(value);
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(json).toString('base64url');
+    return btoa(unescape(encodeURIComponent(json))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function decode(cursor, expectedBinding) {
+    try {
+        const json = typeof Buffer !== 'undefined'
+            ? Buffer.from(cursor, 'base64url').toString('utf8')
+            : (() => {
+                const base64 = cursor.replace(/-/g, '+').replace(/_/g, '/');
+                return decodeURIComponent(escape(atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='))));
+            })();
+        const value = JSON.parse(json);
+        if (value.v !== 1 || value.binding !== expectedBinding || !Array.isArray(value.values) || typeof value.key !== 'string')
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new Error('INVALID_CURSOR: cursor is malformed or does not match this query');
+    }
+}
+/** Small deterministic planner/executor owned by an embedded storage boundary. */
+export class EmbeddedQueryEngine {
+    allRows;
+    indexes = new Map();
+    constructor(allRows) {
+        this.allRows = allRows;
+        this.rebuild();
+    }
+    rebuild() {
+        this.indexes.clear();
+        const rows = [...this.allRows()];
+        for (const [key, value] of rows)
+            this.installDefinition(key, value, rows);
+    }
+    apply(key, value) {
+        if (key.startsWith('__indexes__:')) {
+            if (value === undefined)
+                this.indexes.delete(key);
+            else
+                this.installDefinition(key, value, [...this.allRows()]);
+            return;
+        }
+        const separator = key.indexOf(':');
+        if (separator < 1)
+            return;
+        const collection = key.slice(0, separator);
+        for (const index of this.indexes.values()) {
+            if (index.collection !== collection)
+                continue;
+            const old = index.byKey.get(key);
+            if (old) {
+                const oldBucket = index.buckets.get(bucketKey(old.record[index.fields[0].field]));
+                const position = oldBucket?.findIndex(entry => entry.key === key) ?? -1;
+                if (position >= 0)
+                    oldBucket.splice(position, 1);
+                index.byKey.delete(key);
+            }
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                const entry = { key, record: value };
+                const keyForBucket = bucketKey(entry.record[index.fields[0].field]);
+                let bucket = index.buckets.get(keyForBucket);
+                if (!bucket) {
+                    bucket = [];
+                    index.buckets.set(keyForBucket, bucket);
+                }
+                let low = 0, high = bucket.length;
+                while (low < high) {
+                    const middle = (low + high) >>> 1;
+                    if (compareBySpecs(collection, index.fields, bucket[middle], entry) <= 0)
+                        low = middle + 1;
+                    else
+                        high = middle;
+                }
+                bucket.splice(low, 0, entry);
+                index.byKey.set(key, entry);
+            }
+            index.globalDirty = true;
+        }
+    }
+    installDefinition(key, value, rows) {
+        const parts = key.split(':');
+        if (parts.length < 3 || parts[0] !== '__indexes__' || !value || typeof value !== 'object')
+            return;
+        const config = value.config;
+        if (!config?.name)
+            return;
+        const collection = parts[1];
+        const indexFields = fields(config);
+        if (!indexFields.length || config.type === 'text')
+            return;
+        const prefix = `${collection}:`;
+        const entries = rows
+            .filter(([rowKey, row]) => rowKey.startsWith(prefix) && row && typeof row === 'object' && !Array.isArray(row))
+            .map(([rowKey, row]) => ({ key: rowKey, record: row }));
+        entries.sort((left, right) => compareBySpecs(collection, indexFields, left, right));
+        const buckets = new Map();
+        for (const entry of entries) {
+            const keyForBucket = bucketKey(entry.record[indexFields[0].field]);
+            const bucket = buckets.get(keyForBucket) ?? [];
+            bucket.push(entry);
+            buckets.set(keyForBucket, bucket);
+        }
+        this.indexes.set(key, { collection, config, fields: indexFields, entries, byKey: new Map(entries.map(entry => [entry.key, entry])), buckets, globalDirty: false });
+    }
+    plan(query) {
+        const equality = new Map((query.where ?? []).filter(value => 'eq' in value).map(value => [value.field, value.eq]));
+        const requested = query.orderBy ?? [];
+        for (const index of this.indexes.values()) {
+            if (index.collection !== query.collection)
+                continue;
+            let prefix = 0;
+            while (prefix < index.fields.length && equality.has(index.fields[prefix].field))
+                prefix += 1;
+            if (prefix === 0 && (query.where?.length ?? 0) > 0)
+                continue;
+            const remaining = index.fields.slice(prefix);
+            const exact = requested.every((order, offset) => remaining[offset]?.field === order.field && remaining[offset]?.direction === order.direction);
+            const automaticIdTie = remaining.length === requested.length;
+            const declaredIdTie = remaining.length === requested.length + 1 && remaining.at(-1)?.field === 'id' && remaining.at(-1)?.direction === 'asc';
+            if (requested.length && (!exact || (!automaticIdTie && !declaredIdTie)))
+                continue;
+            return {
+                index,
+                explanation: { plan: requested.length ? 'index-range' : 'index-filter', index: index.config.name, order: this.orderDescription(query), limit: query.limit, cursor: Boolean(query.cursor) },
+            };
+        }
+        return { explanation: { plan: 'full-scan', reason: 'no compatible index', order: this.orderDescription(query), limit: query.limit, cursor: Boolean(query.cursor) } };
+    }
+    explain(query) {
+        this.validate(query);
+        return this.plan(query).explanation;
+    }
+    execute(query) {
+        this.validate(query);
+        const started = now();
+        const planned = this.plan(query);
+        const stats = { scanned: 0, decoded: 0, matched: 0, sorted: 0, materialized: 0, returned: 0, usedIndex: Boolean(planned.index), indexName: planned.index?.config.name, indexLookupMs: 0, executionMs: 0 };
+        const conditions = query.where ?? [];
+        const order = query.orderBy ?? [];
+        const outputSpecs = order.map(value => ({ field: value.field, direction: value.direction }));
+        const cursor = query.cursor ? decode(query.cursor, binding(query)) : undefined;
+        const range = planned.index
+            ? this.indexRange(planned.index, conditions)
+            : (() => {
+                const entries = [...this.allRows()].filter(([key]) => key.startsWith(`${query.collection}:`)).map(([key, value]) => ({ key, record: value }));
+                return { entries, start: 0, end: entries.length };
+            })();
+        const candidates = range.entries;
+        let candidateStart = range.start;
+        if (planned.index && cursor) {
+            let low = range.start;
+            let high = range.end;
+            while (low < high) {
+                const middle = (low + high) >>> 1;
+                if (this.compareEntryCursor(query.collection, outputSpecs, candidates[middle], cursor) <= 0)
+                    low = middle + 1;
+                else
+                    high = middle;
+            }
+            candidateStart = low;
+        }
+        let matching = [];
+        const lookupStarted = now();
+        for (let candidateIndex = candidateStart; candidateIndex < range.end; candidateIndex += 1) {
+            const entry = candidates[candidateIndex];
+            stats.scanned += 1;
+            if (!entry.record || typeof entry.record !== 'object' || !conditions.every(condition => conditionMatches(entry.record, condition)))
+                continue;
+            stats.matched += 1;
+            matching.push(entry);
+            if (planned.index && matching.length > query.limit)
+                break;
+        }
+        stats.indexLookupMs = planned.index ? now() - lookupStarted : 0;
+        const fullScanMaterialized = matching.length;
+        if (!planned.index) {
+            matching.sort((left, right) => compareBySpecs(query.collection, outputSpecs, left, right));
+            stats.sorted = matching.length;
+            if (cursor)
+                matching = matching.filter(entry => this.afterCursor(query.collection, outputSpecs, entry, cursor));
+        }
+        const hasMore = matching.length > query.limit;
+        const pageEntries = matching.slice(0, query.limit);
+        const records = pageEntries.map(entry => entry.record);
+        stats.materialized = planned.index ? records.length : fullScanMaterialized;
+        stats.returned = records.length;
+        stats.executionMs = now() - started;
+        const last = pageEntries.at(-1);
+        const nextCursor = hasMore && last ? encode({ v: 1, binding: binding(query), values: order.map(value => last.record[value.field]), key: recordId(query.collection, last.key, last.record) }) : undefined;
+        return {
+            records,
+            ...(nextCursor ? { nextCursor } : {}),
+            exhausted: !nextCursor,
+            stats,
+            plan: { access_method: planned.explanation.plan, actual_rows_scanned: stats.scanned, actual_rows_returned: stats.returned, matching_records: stats.matched, index: stats.indexName, scan_fallback: !stats.usedIndex },
+        };
+    }
+    afterCursor(collection, order, entry, cursor) {
+        return this.compareEntryCursor(collection, order, entry, cursor) > 0;
+    }
+    compareEntryCursor(collection, order, entry, cursor) {
+        for (let index = 0; index < order.length; index += 1) {
+            const compared = compareValue(entry.record[order[index].field], cursor.values[index]);
+            if (compared)
+                return order[index].direction === 'asc' ? compared : -compared;
+        }
+        return recordId(collection, entry.key, entry.record).localeCompare(cursor.key);
+    }
+    indexRange(index, conditions) {
+        const equality = new Map(conditions.filter(value => 'eq' in value).map(value => [value.field, value.eq]));
+        let count = 0;
+        while (count < index.fields.length && equality.has(index.fields[count].field))
+            count += 1;
+        if (count === 0) {
+            if (index.globalDirty) {
+                index.entries = [...index.byKey.values()].sort((left, right) => compareBySpecs(index.collection, index.fields, left, right));
+                index.globalDirty = false;
+            }
+            return { entries: index.entries, start: 0, end: index.entries.length };
+        }
+        const entries = index.buckets.get(bucketKey(equality.get(index.fields[0].field))) ?? [];
+        if (count === 1)
+            return { entries, start: 0, end: entries.length };
+        const comparePrefix = (entry) => {
+            for (let position = 0; position < count; position += 1) {
+                const spec = index.fields[position];
+                const compared = compareValue(entry.record[spec.field], equality.get(spec.field));
+                if (compared)
+                    return spec.direction === 'asc' ? compared : -compared;
+            }
+            return 0;
+        };
+        let low = 0, high = entries.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (comparePrefix(entries[middle]) < 0)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        const start = low;
+        high = entries.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (comparePrefix(entries[middle]) <= 0)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        return { entries, start, end: low };
+    }
+    orderDescription(query) {
+        return [...(query.orderBy ?? []).map(value => `${value.field} ${value.direction.toUpperCase()}`), 'id ASC'].join(', ');
+    }
+    validate(query) {
+        if (!query.collection?.trim() || !Number.isInteger(query.limit) || query.limit < 1 || query.limit > 1_000)
+            throw new Error('INVALID_QUERY: collection and a limit between 1 and 1000 are required');
+        for (const condition of query.where ?? []) {
+            const operators = ['eq', 'neq', 'lt', 'lte', 'gt', 'gte'].filter(operator => operator in condition);
+            if (!condition.field || operators.length !== 1)
+                throw new Error('INVALID_QUERY: each condition requires one operator');
+        }
+    }
+}

package/dist/feltdb-vision-invariants.d.ts

@@ -0,0 +1,46 @@
+/**
+ * FeltDB's own architectural invariants, as durable declarations.
+ *
+ * `docs/history/reports/VISION_INVARIANTS.md` is the human-readable source.
+ * This module is the same statements in the durable model, carrying the stable
+ * ids `FELTDB-001` … `FELTDB-009` that appear in that document, so the two can
+ * be compared rather than silently diverging. `npm run check:vision-invariants`
+ * compares them on every change.
+ *
+ * FeltDB is the first consumer of its own invariant substrate. It declares
+ * what must remain true; an advisory evaluator says whether the evidence it
+ * collected looks consistent with that, and the evaluation is retained here.
+ * Nothing in this module evaluates anything.
+ */
+import type { CreateArchitectureInvariantInput, FeltDBArchitectureInvariantService } from './architecture-invariant.js';
+import type { ArchitectureInvariant } from './architecture-invariant.js';
+/** Scope every FeltDB invariant is declared over. */
+export declare const FELTDB_VISION_SCOPE = "feltdb";
+/** Category grouping the invariants that come from the Vision Invariants document. */
+export declare const FELTDB_VISION_CATEGORY = "vision";
+/**
+ * The declarations, in document order.
+ *
+ * Each `description` is the statement as the Vision Invariants document words
+ * it. Each `verification` entry names something that exists in this repository
+ * — a test, a repository check, or the source that implements the invariant —
+ * so an evaluator has somewhere real to look, and `human-review` is used where
+ * the honest answer is that a person decides.
+ */
+export declare const FELTDB_VISION_INVARIANTS: readonly CreateArchitectureInvariantInput[];
+export interface SeedInvariantOutcome {
+    id: string;
+    /** `created` on first declaration, `versioned` when the wording changed. */
+    outcome: 'created' | 'versioned' | 'unchanged';
+    version: number;
+    invariant: ArchitectureInvariant;
+}
+/**
+ * Declare FeltDB's own invariants into a FeltDB database.
+ *
+ * Idempotent, and honest about what it did: an invariant that is already
+ * declared with the same wording is left alone, and one whose wording changed
+ * becomes a new version rather than a rewrite of the old one.
+ */
+export declare function seedFeltDBVisionInvariants(service: FeltDBArchitectureInvariantService, declarations?: readonly CreateArchitectureInvariantInput[], reason?: string): Promise<SeedInvariantOutcome[]>;
+//# sourceMappingURL=feltdb-vision-invariants.d.ts.map

package/dist/feltdb-vision-invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feltdb-vision-invariants.d.ts","sourceRoot":"","sources":["../src/feltdb-vision-invariants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,gCAAgC,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAC;AACxH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEzE,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAC5C,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,WAAW,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,gCAAgC,EAqK/E,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,kCAAkC,EAC3C,YAAY,GAAE,SAAS,gCAAgC,EAA6B,EACpF,MAAM,SAA4D,GACjE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAwBjC"}

package/dist/feltdb-vision-invariants.js

@@ -0,0 +1,213 @@
+/** Scope every FeltDB invariant is declared over. */
+export const FELTDB_VISION_SCOPE = 'feltdb';
+/** Category grouping the invariants that come from the Vision Invariants document. */
+export const FELTDB_VISION_CATEGORY = 'vision';
+/**
+ * The declarations, in document order.
+ *
+ * Each `description` is the statement as the Vision Invariants document words
+ * it. Each `verification` entry names something that exists in this repository
+ * — a test, a repository check, or the source that implements the invariant —
+ * so an evaluator has somewhere real to look, and `human-review` is used where
+ * the honest answer is that a person decides.
+ */
+export const FELTDB_VISION_INVARIANTS = [
+    {
+        id: 'FELTDB-001',
+        name: 'Collections feel like native state',
+        description: 'Applications use collection.get, all, where, insert, update, delete, and subscribe; '
+            + 'storage and network topology stay behind that API.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'automated-test', reference: 'test:e2e/acceptance.test.ts' },
+            { method: 'source-analysis', reference: 'file:packages/core/src/collection.ts' },
+            {
+                method: 'jev-advisory',
+                evaluator: 'jev',
+                predicate: 'the change keeps storage runtime and network topology behind the collection API',
+            },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-002',
+        name: 'One canonical mutation path',
+        description: 'Embedded, HTTP, replicated, workflow, and agent changes become the same durable operation. '
+            + 'Adapters may transport operations but may not invent a second store.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'contract-conformance', reference: 'command:check:public-contract' },
+            { method: 'automated-test', reference: 'test:e2e/conditional-write-runtime-parity.test.mjs' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change keeps every durable mutation on the one canonical operation path and adds no second store' },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-003',
+        name: 'Local-first operation',
+        description: 'Local reads and writes do not require a network round trip. Offline mutations retain '
+            + 'causal identity and converge when peers return.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'automated-test', reference: 'test:e2e/file-runtime-authority.test.mjs' },
+            { method: 'runtime-observation', reference: 'test:e2e/pr30-partition-healing-convergence.test.mjs' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change keeps local reads and writes free of a required network round trip' },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-004',
+        name: 'Reactivity is a database guarantee',
+        description: 'A committed local or remote mutation reaches live collections without '
+            + 'application-managed refetch, invalidation, or cache synchronization.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'automated-test', reference: 'test:e2e/pr25-subscription-lifecycle.test.mjs' },
+            { method: 'source-analysis', reference: 'file:packages/core/src/reactive-graph.ts' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change keeps committed mutations reaching live collections without application-managed refetch or cache synchronization' },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-005',
+        name: 'References describe identity, not location',
+        description: 'flow:// references survive movement between runtimes; acquisition and routing resolve '
+            + 'them without leaking topology into application code.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'automated-test', reference: 'test:e2e/peer-acquisition.test.mjs' },
+            { method: 'source-analysis', reference: 'file:packages/core/src/sync-contract.ts' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change keeps flow:// references identity-bearing and does not leak runtime topology into application code' },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-006',
+        name: 'Distribution preserves causality',
+        description: 'Replication retains origin and sequence, verifies content, rejects gaps, deduplicates '
+            + 'delivery, and never translates remote writes into unrelated local ones.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'contract-conformance', reference: 'command:check:causal-authority' },
+            { method: 'automated-test', reference: 'test:e2e/pr27-three-node-catchup-convergence.test.mjs' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change preserves replication origin, sequence, content verification, gap rejection, and delivery deduplication' },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-007',
+        name: 'Capabilities derive from state',
+        description: 'Search, vectors, workflows, and agents consume and produce canonical state transitions '
+            + 'rather than maintaining authoritative side databases.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'automated-test', reference: 'test:e2e/state-trigger-workload.test.mjs' },
+            { method: 'source-analysis', reference: 'file:packages/core/src/capability.ts' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change keeps capabilities deriving from canonical state and introduces no authoritative side database' },
+        ],
+        references: [{
+                authority: '.flow',
+                reference: 'feltdb.flow',
+                relationship: 'FeltDB must not introduce an independent authoritative representation of a .flow declaration; '
+                    + 'it compiles the declaration that .flow owns.',
+            }],
+    },
+    {
+        id: 'FELTDB-008',
+        name: 'Unavailable means unavailable',
+        description: 'Runtime discovery and health must not advertise scaffolded or simulated functionality '
+            + 'as production-ready.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'contract-conformance', reference: 'command:check:managed-no-fallback' },
+            { method: 'automated-test', reference: 'test:e2e/public-contract-authority-loss.test.mjs' },
+            {
+                method: 'human-review',
+                notes: 'Whether a newly declared capability is genuinely production-ready is a judgment, '
+                    + 'not a measurement. The checks catch a silent fallback; they cannot catch an honest mistake.',
+            },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change does not advertise scaffolded or simulated functionality as production-ready' },
+        ],
+        references: [],
+    },
+    {
+        id: 'FELTDB-009',
+        name: 'Durable state has one authority',
+        description: 'Every durable fact has exactly one canonical owner inside FeltDB. Events, indexes, '
+            + 'caches, projections, and adapters are derived and rebuildable, never an independent source of '
+            + 'truth, and every durable operation carries explicit tenant and application scope and provenance.',
+        category: FELTDB_VISION_CATEGORY,
+        severity: 'critical',
+        scope: FELTDB_VISION_SCOPE,
+        verification: [
+            { method: 'contract-conformance', reference: 'command:check:public-contract' },
+            { method: 'contract-conformance', reference: 'command:check:managed-authority' },
+            { method: 'source-analysis', reference: 'file:packages/core/src/authority-scope.ts' },
+            { method: 'jev-advisory', evaluator: 'jev',
+                predicate: 'the change keeps one canonical authority for every durable fact, with derived projections rebuildable and durable operations explicitly scoped' },
+        ],
+        references: [{
+                authority: 'authboundry',
+                reference: 'authorization decisions',
+                relationship: 'FeltDB stores the authorization decision identity as provenance and does not re-decide it. '
+                    + 'Who may act remains AuthBoundry\'s; where a durable fact lives remains FeltDB\'s.',
+            }],
+    },
+];
+/**
+ * Declare FeltDB's own invariants into a FeltDB database.
+ *
+ * Idempotent, and honest about what it did: an invariant that is already
+ * declared with the same wording is left alone, and one whose wording changed
+ * becomes a new version rather than a rewrite of the old one.
+ */
+export async function seedFeltDBVisionInvariants(service, declarations = FELTDB_VISION_INVARIANTS, reason = 'synchronized with the FeltDB Vision Invariants document') {
+    const outcomes = [];
+    for (const declaration of declarations) {
+        let existing;
+        try {
+            existing = await service.invariants.get(declaration.id);
+        }
+        catch (error) {
+            if (error.code !== 'NOT_FOUND')
+                throw error;
+        }
+        if (!existing) {
+            const invariant = await service.invariants.create(declaration);
+            outcomes.push({ id: declaration.id, outcome: 'created', version: invariant.version, invariant });
+            continue;
+        }
+        const { id: _id, ...changes } = declaration;
+        const invariant = await service.invariants.update(declaration.id, { ...changes, reason });
+        outcomes.push({
+            id: declaration.id,
+            outcome: invariant.version === existing.version ? 'unchanged' : 'versioned',
+            version: invariant.version,
+            invariant,
+        });
+    }
+    return outcomes;
+}

package/dist/feltdb.d.ts

@@ -40,8 +40,19 @@ export interface JsDb {
      * Query data
      */
     query(query: string): any | Promise<any>;
-    /** Execute a bounded query inside a remote authority. Embedded runtimes omit it. */
+    /** Execute a bounded query at the runtime's storage boundary. */
     authority_query?(query: unknown): Promise<unknown>;
+    /**
+     * Plain `Collection.find(query)` should delegate to `authority_query`.
+     *
+     * Embedded runtimes may expose `authority_query` for bounded execution while
+     * still keeping the unbounded Collection API on the local cache/index path.
+     */
+    collection_queries_via_authority?: boolean;
+    /** Explain a bounded query without executing it. */
+    explain_query?(query: unknown): unknown | Promise<unknown>;
+    /** Rebuild derived embedded indexes from authoritative records. */
+    rebuild_indexes?(): void | Promise<void>;
     /**
      * Get a record
      */

package/dist/feltdb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"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"}

package/dist/file-db.d.ts

@@ -2,6 +2,7 @@ import type { JsDb } from './feltdb.js';
 import type { FreshnessCapability } from './freshness.js';
 import type { OperationAdmissionInput, OperationAdmissionResult, OperationTransitionInput, OperationTransitionResult } from './operation-admission.js';
 import type { AtomicTransactionRequest, AtomicTransactionResult } from './transaction.js';
+import type { AuthorityQueryRequest } from './http-db.js';
 interface JsResult {
     success: boolean;
     data?: string;
@@ -27,6 +28,8 @@ export declare class FileJsDb implements JsDb {
     private lockFd;
     private lockToken;
     private readonly applied;
+    private readonly queryEngine;
+    private indexedSequence;
     constructor(path: string);
     private loadState;
     private loadStateFromBackup;
@@ -59,6 +62,11 @@ export declare class FileJsDb implements JsDb {
     get(key: string): JsResult;
     delete(key: string): JsResult;
     query(capability: string): JsResult;
+    authority_query<T = Record<string, unknown>>(query: AuthorityQueryRequest): Promise<import("./http-db.js").AuthorityQueryPage<T> & {
+        stats: import("./embedded-query.js").EmbeddedQueryStats;
+    }>;
+    explain_query(query: AuthorityQueryRequest): import("./embedded-query.js").EmbeddedQueryExplanation;
+    rebuild_indexes(): void;
     get_capability_records(capability: string): JsResult;
     execute_op(): JsResult;
     sync_info(): JsResult;