@feltdb/core 0.6.9 → 0.6.11

package/dist/development-runtime-bridge.js

@@ -0,0 +1,171 @@
+/** Maximum unsent events retained by a runtime. New events are dropped beyond this bound. */
+export const DEVELOPMENT_OBSERVATION_BUFFER_LIMIT = 256;
+let configuredSession;
+/** Supply ephemeral `feltdb dev` identity. This is a no-op when values are absent. */
+export function configureDevelopmentRuntimeBridge(session) {
+    if (!session) {
+        configuredSession = undefined;
+        return;
+    }
+    if (!session.sessionId || !session.workspaceId || !session.namespace || !session.runtime || !session.authorityUrl || !session.bridgeUrl)
+        return;
+    configuredSession = session;
+}
+function randomId() {
+    const value = globalThis.crypto?.randomUUID?.().replace(/-/g, '')
+        ?? `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+    return `runtime_${value}`;
+}
+function processSession() {
+    const environment = globalThis.process?.env;
+    if (!environment?.FELTDB_DEV_SESSION_ID)
+        return undefined;
+    return {
+        sessionId: environment.FELTDB_DEV_SESSION_ID,
+        workspaceId: environment.FELTDB_WORKSPACE_ID,
+        namespace: environment.FELTDB_NAMESPACE,
+        runtime: environment.FELTDB_RUNTIME,
+        authorityUrl: environment.FELTDB_AUTHORITY_URL || environment.FELTDB_WORKSPACE_ENDPOINT,
+        bridgeUrl: environment.FELTDB_DEV_BRIDGE_URL,
+        applicationUrl: environment.FELTDB_APPLICATION_URL,
+    };
+}
+function safeBridgeUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1', '[::1]'].includes(url.hostname))
+            return undefined;
+        return url.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Internal, optional registration hook called by Core runtime construction. */
+export function attachDevelopmentRuntimeBridge(input) {
+    const runtimeInstanceId = randomId();
+    let activeSession;
+    let heartbeat;
+    let flushTimer;
+    let flushing = false;
+    let closing = false;
+    let dropped = 0;
+    const observations = [];
+    const applicationId = input.applicationId
+        || globalThis.document?.title
+        || globalThis.process?.env?.npm_package_name
+        || 'application';
+    const register = async (candidate) => {
+        const session = candidate || configuredSession || processSession();
+        const compatibleRuntime = session?.runtime === input.runtime
+            || (input.runtime === 'remote' && ['managed', 'self-hosted', 'remote'].includes(session?.runtime || ''));
+        if (!session || session.namespace !== input.namespace || !compatibleRuntime)
+            return;
+        const bridgeUrl = safeBridgeUrl(session.bridgeUrl);
+        if (!bridgeUrl)
+            return;
+        activeSession = { ...session, bridgeUrl };
+        const registration = { ...activeSession, runtimeInstanceId, applicationId };
+        try {
+            const response = await fetch(`${bridgeUrl}/api/v1/development/runtime/register`, {
+                method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(registration),
+            });
+            if (!response.ok)
+                return;
+            if (!heartbeat) {
+                heartbeat = setInterval(() => { void register(activeSession); }, 2000);
+                heartbeat.unref?.();
+            }
+        }
+        catch { /* Development tooling is optional. */ }
+    };
+    const flush = async () => {
+        if (flushing || !activeSession || observations.length === 0)
+            return;
+        flushing = true;
+        const batch = observations.splice(0, 32);
+        const droppedEvents = dropped;
+        dropped = 0;
+        try {
+            const response = await fetch(`${activeSession.bridgeUrl}/api/v1/development/runtime/${encodeURIComponent(runtimeInstanceId)}/observations`, {
+                method: 'POST', headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ sessionId: activeSession.sessionId, observations: batch, dropped: droppedEvents }),
+            });
+            if (!response.ok)
+                throw new Error('observation delivery failed');
+        }
+        catch {
+            if (!closing) {
+                const available = DEVELOPMENT_OBSERVATION_BUFFER_LIMIT - observations.length;
+                observations.unshift(...batch.slice(Math.max(0, batch.length - available)));
+                dropped += droppedEvents + Math.max(0, batch.length - available);
+            }
+        }
+        finally {
+            flushing = false;
+            if (observations.length && !closing) {
+                flushTimer = setTimeout(() => { flushTimer = undefined; void flush(); }, 100);
+                flushTimer.unref?.();
+            }
+        }
+    };
+    const enqueue = (event) => {
+        if (!activeSession || closing)
+            return;
+        if (observations.length >= DEVELOPMENT_OBSERVATION_BUFFER_LIMIT)
+            dropped++;
+        else
+            observations.push(event);
+        if (!flushTimer && !flushing) {
+            flushTimer = setTimeout(() => { flushTimer = undefined; void flush(); }, 0);
+            flushTimer.unref?.();
+        }
+    };
+    const observation = {
+        start(type, details = {}) {
+            const correlationId = `op_${randomId().slice(8)}`;
+            const startedAt = Date.now();
+            const emit = (status, metadata, error) => enqueue({
+                eventId: `evt_${randomId().slice(8)}`, correlationId, timestamp: Date.now(),
+                workspaceId: activeSession?.workspaceId, sessionId: activeSession?.sessionId, runtimeInstanceId,
+                operation: { type, collection: details.collection, transactionId: details.transactionId }, status,
+                durationMs: status === 'started' ? undefined : Date.now() - startedAt,
+                metadata: metadata || details.metadata,
+                error: status === 'failed' ? {
+                    code: typeof error === 'object' && error && 'code' in error ? String(error.code) : undefined,
+                    message: (error instanceof Error ? error.message : String(error)).slice(0, 500),
+                } : undefined,
+            });
+            emit('started');
+            return { complete: metadata => emit('completed', metadata), fail: error => emit('failed', undefined, error) };
+        },
+    };
+    const browser = globalThis.window;
+    const receive = (event) => {
+        if (event.source !== browser?.parent || event.data?.type !== 'feltdb:dev-session')
+            return;
+        void register(event.data.session);
+    };
+    browser?.addEventListener?.('message', receive);
+    void register();
+    const close = async () => {
+        closing = true;
+        if (heartbeat)
+            clearInterval(heartbeat);
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        while (observations.length)
+            await flush();
+        browser?.removeEventListener?.('message', receive);
+        if (!activeSession)
+            return;
+        try {
+            await fetch(`${activeSession.bridgeUrl}/api/v1/development/runtime/${encodeURIComponent(runtimeInstanceId)}?sessionId=${encodeURIComponent(activeSession.sessionId)}`, {
+                method: 'DELETE', keepalive: true,
+            });
+        }
+        catch { /* Lease expiry handles crashes and unavailable tooling. */ }
+    };
+    browser?.addEventListener?.('pagehide', () => { void close(); }, { once: true });
+    return { runtimeInstanceId, observation, close };
+}

package/dist/embedded-transaction.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Transaction semantics for embedded runtimes.
+ *
+ * FeltDB has one transaction contract. The authority-backed runtime satisfies
+ * it by handing the staged transaction to the store's own atomic commit path;
+ * the embedded runtimes satisfy it here.
+ *
+ * The semantics live in this module *once*. A runtime does not reimplement
+ * them — it supplies only the thing that is genuinely runtime-specific: its
+ * atomic durable commit boundary.
+ *
+ * ```text
+ *                 db.transaction()
+ *                       │
+ *                staged operations
+ *                       │
+ *              ┌────────┴────────┐
+ *              │                 │
+ *          authority          embedded
+ *      (store's atomic     (decidePlan here +
+ *       commit path)        runtime commit)
+ *              │                 │
+ *              └────────┬────────┘
+ *                       │
+ *                atomic durable
+ *                     commit
+ * ```
+ *
+ * The decision step is pure: it reads current state and produces a plan. It
+ * performs no I/O and mutates nothing, so a runtime can evaluate the whole
+ * transaction before touching storage and then apply the plan in one atomic
+ * step. That ordering is what makes partial application impossible.
+ */
+import type { AtomicTransactionRequest, AtomicTransactionResult } from './transaction.js';
+/** One resolved mutation. An absent `value` means delete. */
+export interface EmbeddedMutation {
+    /** Storage key, `collection:id`. */
+    key: string;
+    collection: string;
+    id: string;
+    value?: Record<string, unknown>;
+}
+/** What a runtime must be able to tell the decision step. */
+export interface EmbeddedTransactionState {
+    /** Whether a record currently exists. */
+    exists(key: string): boolean;
+    /** Whether this transaction id has already been committed. */
+    hasApplied(transactionId: string): boolean;
+}
+export type EmbeddedPlan = {
+    kind: 'duplicate';
+} | {
+    kind: 'reject';
+    reason: string;
+} | {
+    kind: 'apply';
+    mutations: EmbeddedMutation[];
+};
+/** Storage key for a collection and id. */
+export declare function recordKey(collection: string, id: string): string;
+/**
+ * Decide what a transaction should do, without doing any of it.
+ *
+ * Returns `duplicate` when this transaction id was already committed (so
+ * redelivery is a no-op), `reject` when the transaction cannot commit at all,
+ * or `apply` with every mutation resolved.
+ *
+ * A rejection means nothing may be written. There is no partial plan.
+ */
+export declare function decideTransaction(request: AtomicTransactionRequest, state: EmbeddedTransactionState): EmbeddedPlan;
+/** Shape a runtime returns after committing. */
+export declare function embeddedResult(request: AtomicTransactionRequest, duplicate: boolean, stateBefore: number, stateAfter: number): AtomicTransactionResult;
+/** Raised when a transaction is refused. Nothing was written. */
+export declare class EmbeddedTransactionRejected extends Error {
+    constructor(reason: string);
+}
+//# sourceMappingURL=embedded-transaction.d.ts.map

package/dist/embedded-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-transaction.d.ts","sourceRoot":"","sources":["../src/embedded-transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE1F,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,8DAA8D;IAC9D,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAErD,2CAA2C;AAC3C,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhE;AAID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,wBAAwB,GAC9B,YAAY,CA0Cd;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,wBAAwB,EACjC,SAAS,EAAE,OAAO,EAClB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,uBAAuB,CAQzB;AAED,iEAAiE;AACjE,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,MAAM,EAAE,MAAM;CAI3B"}

package/dist/embedded-transaction.js

@@ -0,0 +1,102 @@
+/**
+ * Transaction semantics for embedded runtimes.
+ *
+ * FeltDB has one transaction contract. The authority-backed runtime satisfies
+ * it by handing the staged transaction to the store's own atomic commit path;
+ * the embedded runtimes satisfy it here.
+ *
+ * The semantics live in this module *once*. A runtime does not reimplement
+ * them — it supplies only the thing that is genuinely runtime-specific: its
+ * atomic durable commit boundary.
+ *
+ * ```text
+ *                 db.transaction()
+ *                       │
+ *                staged operations
+ *                       │
+ *              ┌────────┴────────┐
+ *              │                 │
+ *          authority          embedded
+ *      (store's atomic     (decidePlan here +
+ *       commit path)        runtime commit)
+ *              │                 │
+ *              └────────┬────────┘
+ *                       │
+ *                atomic durable
+ *                     commit
+ * ```
+ *
+ * The decision step is pure: it reads current state and produces a plan. It
+ * performs no I/O and mutates nothing, so a runtime can evaluate the whole
+ * transaction before touching storage and then apply the plan in one atomic
+ * step. That ordering is what makes partial application impossible.
+ */
+/** Storage key for a collection and id. */
+export function recordKey(collection, id) {
+    return `${collection}:${id}`;
+}
+const SEGMENT = /^[A-Za-z0-9._-]{1,128}$/;
+/**
+ * Decide what a transaction should do, without doing any of it.
+ *
+ * Returns `duplicate` when this transaction id was already committed (so
+ * redelivery is a no-op), `reject` when the transaction cannot commit at all,
+ * or `apply` with every mutation resolved.
+ *
+ * A rejection means nothing may be written. There is no partial plan.
+ */
+export function decideTransaction(request, state) {
+    if (!request.transactionId || !request.transactionId.trim()) {
+        return { kind: 'reject', reason: 'transactionId is required' };
+    }
+    if (request.operations.length === 0) {
+        return { kind: 'reject', reason: 'a transaction requires at least one operation' };
+    }
+    if (state.hasApplied(request.transactionId)) {
+        return { kind: 'duplicate' };
+    }
+    const mutations = [];
+    const seen = new Set();
+    for (const operation of request.operations) {
+        if (!SEGMENT.test(operation.collection) || !SEGMENT.test(operation.id)) {
+            return {
+                kind: 'reject',
+                reason: `invalid collection or id: ${operation.collection}:${operation.id}`,
+            };
+        }
+        const key = recordKey(operation.collection, operation.id);
+        if (seen.has(key)) {
+            return { kind: 'reject', reason: `transaction writes ${key} more than once` };
+        }
+        seen.add(key);
+        if (operation.requireAbsent && state.exists(key)) {
+            return { kind: 'reject', reason: `PRECONDITION_FAILED:${key}:record already exists` };
+        }
+        mutations.push({
+            key,
+            collection: operation.collection,
+            id: operation.id,
+            value: operation.value === undefined
+                ? undefined
+                : { ...operation.value, id: operation.id },
+        });
+    }
+    return { kind: 'apply', mutations };
+}
+/** Shape a runtime returns after committing. */
+export function embeddedResult(request, duplicate, stateBefore, stateAfter) {
+    return {
+        transactionId: request.transactionId,
+        duplicate,
+        operations: request.operations.length,
+        stateBefore,
+        stateAfter,
+    };
+}
+/** Raised when a transaction is refused. Nothing was written. */
+export class EmbeddedTransactionRejected extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = 'EmbeddedTransactionRejected';
+    }
+}

package/dist/feltdb.d.ts

@@ -3,6 +3,7 @@
  *
  * This is the FFI interface to the Rust WASM implementation.
  */
+import type { FreshnessCapability, Revision } from './freshness.js';
 /**
  * WASM database instance
  */
@@ -63,9 +64,34 @@ export interface JsDb {
      */
     instance_id(): string;
     /**
-     * Get sequence number
+     * Get sequence number.
+     *
+     * **Not a freshness token.** This means something different in every runtime:
+     * a hardcoded `0` over HTTP, the number of mutations this handle performed in
+     * the memory and browser runtimes, and the loaded snapshot's counter in the
+     * file runtime. None of those reflect a write made by another process, tab,
+     * or node. Use `freshness()` and `revision()` to decide whether a cached copy
+     * is current.
      */
     get_sequence(): number;
+    /**
+     * Declare what freshness validation this runtime can honestly support.
+     *
+     * A runtime implements this only if it has something true to say. Omitting it
+     * is read as "explicit refresh only", which is the safe answer.
+     *
+     * See packages/core/src/freshness.ts for the rule this answer is held to.
+     */
+    freshness?(): FreshnessCapability | Promise<FreshnessCapability>;
+    /**
+     * The current committed-state revision.
+     *
+     * Defined **only** by runtimes whose `freshness()` advertises
+     * `validation: 'revision'`. A runtime that exposes this without advertising
+     * it is a contract violation, because an exposed revision will eventually be
+     * trusted.
+     */
+    revision?(): Promise<Revision>;
     /** Read durable mutation events when the runtime exposes an audit log. */
     audit_events?(): any | Promise<any>;
     /** Export and merge portable embedded-runtime operations. */
@@ -95,6 +121,28 @@ export interface JsDb {
     admitOperation?(input: any): Promise<any>;
     /** Atomic operation lifecycle transition: versioned conditional state changes. */
     transitionOperation?(input: any): Promise<any>;
+    /**
+     * Commit several operations as one atomic, durable transaction.
+     *
+     * A runtime implements this only when it is backed by an authority that can
+     * provide the guarantee. Runtimes that cannot leave it undefined, so callers
+     * get an explicit refusal instead of a silent sequence of separate writes.
+     */
+    commit_transaction?(request: {
+        transactionId: string;
+        operations: Array<{
+            collection: string;
+            id: string;
+            value?: Record<string, unknown>;
+            expectedVersion?: number;
+        }>;
+    }): Promise<{
+        transactionId: string;
+        duplicate: boolean;
+        operations: number;
+        stateBefore: number;
+        stateAfter: number;
+    }>;
 }
 /**
  * A row stored in the database

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

@@ -1,5 +1,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';
 interface JsResult {
     success: boolean;
     data?: string;
@@ -23,6 +25,7 @@ export declare class FileJsDb implements JsDb {
     private readonly origin;
     private readonly peers;
     private lockFd;
+    private readonly applied;
     constructor(path: string);
     private loadState;
     private initializeState;
@@ -33,6 +36,18 @@ export declare class FileJsDb implements JsDb {
     private releaseLockAsync;
     private saveState;
     private event;
+    /**
+     * Commit several operations atomically and durably.
+     *
+     * The snapshot is published by writing a temporary file, fsyncing it, and
+     * renaming it over the previous one. The rename is atomic, so a reader sees
+     * either the whole transaction or none of it, and a crash at any point
+     * leaves one of those two states on disk — never a mixture.
+     *
+     * Order matters here. The next state is built and persisted *before* it is
+     * adopted in memory, so a failed write cannot leave memory ahead of disk.
+     */
+    commit_transaction(request: AtomicTransactionRequest): Promise<AtomicTransactionResult>;
     insert(key: string, value: string): JsResult;
     update(key: string, value: string): JsResult;
     get(key: string): JsResult;
@@ -48,6 +63,24 @@ export declare class FileJsDb implements JsDb {
     get_pending_for_peer(): JsResult;
     instance_id(): string;
     get_sequence(): number;
+    /**
+     * The file runtime declines revision validation, and this is the honest answer
+     * rather than a missing feature.
+     *
+     * A shared directory has no serialization authority over its writers.
+     * `insert`, `update`, `delete`, and `commit_transaction` do not take the
+     * cross-process lock, and publication is a whole-snapshot rename, so two
+     * processes writing the same directory lose data. `state.sequence` therefore
+     * cannot distinguish "one writer committed 50" from "two writers committed 50
+     * each and one snapshot won" — it produces a plausible but false answer,
+     * which is worse than producing none.
+     *
+     * Measured in tools/cli/test/file-runtime-concurrency.test.mjs and analysed in
+     * docs/architecture/freshness-revision-investigation.md. Making this runtime
+     * revision-capable requires fixing lock discipline and publication together;
+     * advertising `refresh` is correct until then, not a placeholder.
+     */
+    freshness(): FreshnessCapability;
     audit_events(): PortableEvent[];
     export_operations(sinceSequence: number): PortableEvent[];
     apply_remote_operations(operations: PortableEvent[]): {

package/dist/file-db.d.ts.map

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