@feltdb/core 0.13.0 → 0.15.0

package/dist/agent-state.js

@@ -32,6 +32,13 @@ export const FELTDB_AGENT_CHECKPOINT_COLLECTION = '_feltdb.AgentCheckpoint';
 export const FELTDB_AGENT_MEMORY_COLLECTION = '_feltdb.AgentMemory';
 export const FELTDB_AGENT_HANDOFF_COLLECTION = '_feltdb.AgentHandoff';
 export const AGENT_CONTEXT_FORMAT = 'feltdb.agent-context@1';
+/**
+ * Index keys written beside every task head so `listTasks` can filter by
+ * project with an equality prefix. Derived from `scope.project` and `status`
+ * on every task write; never returned as part of an `AgentTask`.
+ */
+const TASK_PROJECT_FIELD = 'list_project';
+const TASK_STATUS_PROJECT_FIELD = 'list_status_project';
 /** Compound indexes every agent-state query is planned against. */
 export const AGENT_STATE_INDEXES = [
     {
@@ -54,9 +61,73 @@ export const AGENT_STATE_INDEXES = [
             persistent: true,
         },
     },
+    // listTasks: one index per filter shape, each led by a distinct field, so
+    // every shape has exactly one compatible plan and none is a residual filter.
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_updated',
+            type: 'compound',
+            fields: ['updated_at', 'id'],
+            directions: ['desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_status_updated',
+            type: 'compound',
+            fields: ['status', 'updated_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_project_updated',
+            type: 'compound',
+            fields: [TASK_PROJECT_FIELD, 'updated_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_status_project_updated',
+            type: 'compound',
+            fields: [TASK_STATUS_PROJECT_FIELD, 'updated_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    // listHandoffs
+    {
+        collection: FELTDB_AGENT_HANDOFF_COLLECTION,
+        index: {
+            name: 'agent_handoffs_by_created',
+            type: 'compound',
+            fields: ['created_at', 'id'],
+            directions: ['desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_HANDOFF_COLLECTION,
+        index: {
+            name: 'agent_handoffs_by_status_created',
+            type: 'compound',
+            fields: ['status', 'created_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
 ];
 const TASK_STATUSES = ['ready', 'running', 'blocked', 'completed', 'cancelled'];
 const TERMINAL = ['completed', 'cancelled'];
+const HANDOFF_STATUSES = ['open', 'claimed', 'accepted'];
 /** Every refusal. A refused write committed nothing. */
 export class AgentStateError extends Error {
     code;
@@ -150,6 +221,26 @@ function strip(row) {
     const { id: _id, __version, ...rest } = row;
     return { ...rest, revision: typeof __version === 'number' ? __version : 1 };
 }
+/** A task row without its derived index keys. */
+function toTask(row) {
+    const { [TASK_PROJECT_FIELD]: _project, [TASK_STATUS_PROJECT_FIELD]: _statusProject, ...task } = strip(row);
+    return task;
+}
+/** A task head as written: the task plus the index keys `listTasks` filters on. */
+function taskHead(task) {
+    const project = task.scope?.project;
+    return {
+        ...task,
+        ...(project === undefined ? {} : {
+            [TASK_PROJECT_FIELD]: project,
+            [TASK_STATUS_PROJECT_FIELD]: statusProjectKey(task.status, project),
+        }),
+    };
+}
+function statusProjectKey(status, project) {
+    // A status never contains '|', so the first '|' separates the two.
+    return `${status}|${project}`;
+}
 function version(row) {
     return typeof row.__version === 'number' ? row.__version : 1;
 }
@@ -270,7 +361,7 @@ export class AgentStateStore {
         };
         try {
             await this.db.transaction(tx => {
-                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(taskId, task, { requireAbsent: true });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(taskId, taskHead(task), { requireAbsent: true });
                 tx.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).set(checkpoint.checkpoint_id, checkpoint, { requireAbsent: true });
             });
         }
@@ -286,7 +377,7 @@ export class AgentStateStore {
         const row = await this.taskRow(identifier(taskId, 'taskId'));
         if (!row)
             return null;
-        const task = strip(row);
+        const task = toTask(row);
         const checkpoint = await this.getCheckpoint(task.task_id, task.checkpoint_version);
         if (!checkpoint) {
             throw fail('NOT_FOUND', `task ${taskId} names checkpoint ${task.checkpoint_version}, which is not committed`);
@@ -300,6 +391,30 @@ export class AgentStateStore {
         const { revision: _revision, ...checkpoint } = strip(row);
         return checkpoint;
     }
+    /**
+     * One bounded page of tasks, most recently updated first (ties by task id),
+     * optionally narrowed to a status and/or a project.
+     *
+     * Every filter shape is answered by one declared compound index with an
+     * equality prefix; nothing reads the whole collection. Continue with
+     * `cursor: page.nextCursor` and the same filters.
+     */
+    async listTasks(input = {}) {
+        if (input.status !== undefined && !TASK_STATUSES.includes(input.status)) {
+            throw fail('INVALID_REQUEST', `status must be one of ${TASK_STATUSES.join(', ')}`);
+        }
+        const project = input.project === undefined ? undefined : name(input.project, 'project');
+        const where = project === undefined
+            ? (input.status === undefined ? [] : [{ field: 'status', eq: input.status }])
+            : input.status === undefined
+                ? [{ field: TASK_PROJECT_FIELD, eq: project }]
+                : [{ field: TASK_STATUS_PROJECT_FIELD, eq: statusProjectKey(input.status, project) }];
+        const page = await this.page(FELTDB_AGENT_TASK_COLLECTION, where, 'updated_at', input.limit, input.cursor);
+        return {
+            tasks: page.records.map(toTask),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
     /**
      * Commit checkpoint N+1 atomically with the task head.
      *
@@ -323,7 +438,7 @@ export class AgentStateStore {
             throw fail('INVALID_REQUEST', `evidence must be an array of at most ${LIST_LIMIT} references`);
         }
         const row = await this.requireTask(id);
-        const task = strip(row);
+        const task = toTask(row);
         if (input.expectedVersion !== undefined && input.expectedVersion !== task.checkpoint_version) {
             throw fail('VERSION_CONFLICT', `task ${id} is at checkpoint ${task.checkpoint_version}, not ${input.expectedVersion}`, {
                 expected: input.expectedVersion, current: task.checkpoint_version,
@@ -369,7 +484,7 @@ export class AgentStateStore {
         };
         try {
             await this.db.transaction(tx => {
-                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(id, head, { ifVersion: version(row) });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(id, taskHead(head), { ifVersion: version(row) });
                 tx.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).set(next.checkpoint_id, next, { requireAbsent: true });
                 for (const entry of cited) {
                     if (entry.evidence.kind === 'record') {
@@ -400,7 +515,7 @@ export class AgentStateStore {
      */
     async resume(taskId, input) {
         const row = await this.requireTask(identifier(taskId, 'taskId'));
-        this.assertOwner(strip(row), name(input.actor, 'actor'));
+        this.assertOwner(toTask(row), name(input.actor, 'actor'));
         return this.assembleContext(taskId, input);
     }
     // --------------------------------------------------------------- memory
@@ -414,7 +529,7 @@ export class AgentStateStore {
         const scopeKey = memoryScopeKey(scope);
         if (taskId || scope.kind === 'task') {
             const owningTask = taskId ?? scope.taskId;
-            const task = strip(await this.requireTask(owningTask));
+            const task = toTask(await this.requireTask(owningTask));
             if (scope.kind === 'task' && scope.taskId !== task.task_id) {
                 throw fail('INVALID_REQUEST', `memory for task ${task.task_id} cannot be written to task scope ${scope.taskId}`);
             }
@@ -481,7 +596,7 @@ export class AgentStateStore {
      * its workspace. A memory scoped to another task is never returned.
      */
     async recallForTask(taskId, input = {}) {
-        const task = strip(await this.requireTask(identifier(taskId, 'taskId')));
+        const task = toTask(await this.requireTask(identifier(taskId, 'taskId')));
         const limit = boundedLimit(input.limit, 20, 100);
         const scopes = [
             { kind: 'task', taskId: task.task_id },
@@ -572,7 +687,7 @@ export class AgentStateStore {
         const actor = name(input.actor, 'actor');
         const to = input.to === undefined ? undefined : name(input.to, 'to');
         const row = await this.requireTask(id);
-        const task = strip(row);
+        const task = toTask(row);
         this.assertOwner(task, actor);
         if (TERMINAL.includes(task.status))
             throw fail('INVALID_TRANSITION', `task ${id} is ${task.status}; it cannot be handed off`);
@@ -633,12 +748,34 @@ export class AgentStateStore {
         }
         return resolveHandoff({ ...record, revision: 1 }, task, checkpoint);
     }
+    /**
+     * One bounded page of handoff records, newest first (ties by handoff id).
+     * `open: true` lists the handoffs nobody has claimed yet. Indexed; never a
+     * collection scan.
+     */
+    async listHandoffs(input = {}) {
+        if (input.open === false) {
+            throw fail('INVALID_REQUEST', "open: false is ambiguous; pass status: 'claimed' or 'accepted'");
+        }
+        if (input.status !== undefined && !HANDOFF_STATUSES.includes(input.status)) {
+            throw fail('INVALID_REQUEST', `status must be one of ${HANDOFF_STATUSES.join(', ')}`);
+        }
+        if (input.open && input.status !== undefined && input.status !== 'open') {
+            throw fail('INVALID_REQUEST', `open: true contradicts status: '${input.status}'`);
+        }
+        const status = input.open ? 'open' : input.status;
+        const page = await this.page(FELTDB_AGENT_HANDOFF_COLLECTION, status === undefined ? [] : [{ field: 'status', eq: status }], 'created_at', input.limit, input.cursor);
+        return {
+            handoffs: page.records.map(row => strip(row)),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
     async getHandoff(handoffId) {
         const row = await this.db.collection(FELTDB_AGENT_HANDOFF_COLLECTION).get(identifier(handoffId, 'handoffId', 128));
         if (!row)
             return null;
         const record = strip(row);
-        const task = strip(await this.requireTask(record.task_id));
+        const task = toTask(await this.requireTask(record.task_id));
         const checkpoint = await this.getCheckpoint(record.task_id, record.checkpoint_version);
         if (!checkpoint)
             throw fail('NOT_FOUND', `handoff ${handoffId} references checkpoint ${record.checkpoint_version}, which is not committed`);
@@ -664,7 +801,7 @@ export class AgentStateStore {
         const first = await handoffs.get(id);
         if (!first)
             throw fail('NOT_FOUND', `handoff ${id} does not exist`);
-        const task = strip(await this.requireTask(strip(first).task_id));
+        const task = toTask(await this.requireTask(strip(first).task_id));
         // Decide on a handoff read taken after the task read. A claim commits both
         // records together, so this pair can never show a claimed task beside an
         // open handoff, which would misreport a lost race as a stale handoff.
@@ -710,7 +847,7 @@ export class AgentStateStore {
         try {
             await this.db.transaction(tx => {
                 tx.collection(FELTDB_AGENT_HANDOFF_COLLECTION).set(id, claimed, { ifVersion: handoff.revision });
-                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(task.task_id, head, { ifVersion: task.revision });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(task.task_id, taskHead(head), { ifVersion: task.revision });
             });
         }
         catch (error) {
@@ -760,7 +897,7 @@ export class AgentStateStore {
             }
             throw error;
         }
-        const task = strip(await this.requireTask(handoff.task_id));
+        const task = toTask(await this.requireTask(handoff.task_id));
         return this.resolveRecord({ ...accepted, revision: handoff.revision + 1 }, task);
     }
     // -------------------------------------------------------------- context
@@ -894,6 +1031,31 @@ export class AgentStateStore {
         return bundle;
     }
     // ------------------------------------------------------------- internal
+    async page(collection, where, newestFirst, limit, cursor) {
+        if (cursor !== undefined && (typeof cursor !== 'string' || !cursor)) {
+            throw fail('INVALID_REQUEST', 'cursor must be the nextCursor of a previous page');
+        }
+        let page;
+        try {
+            page = await this.db.query({
+                collection,
+                ...(where.length ? { where } : {}),
+                orderBy: [{ field: newestFirst, direction: 'desc' }],
+                limit: boundedLimit(limit, 50, 1_000),
+                ...(cursor ? { cursor } : {}),
+            });
+        }
+        catch (error) {
+            if (/INVALID_CURSOR/.test(error instanceof Error ? error.message : String(error))) {
+                throw fail('INVALID_REQUEST', 'cursor does not belong to this query; pass the nextCursor of a page with the same filters');
+            }
+            throw error;
+        }
+        return {
+            records: page.records,
+            ...(page.nextCursor && !page.exhausted ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
     async taskRow(taskId) {
         return this.db.collection(FELTDB_AGENT_TASK_COLLECTION).get(taskId);
     }

package/dist/agent.d.ts

@@ -19,7 +19,11 @@ export interface AgentRef {
     toString(): string;
 }
 /**
- * Lifecycle states for agent execution
+ * Lifecycle states for agent execution.
+ *
+ * `Completed`, `Failed` and `Cancelled` are terminal. `Cancelled` is reachable
+ * from every non-terminal state, through `AgentRuntime.cancel` or
+ * `transition(execution, Cancelled)`.
  */
 export declare enum AgentExecutionStatus {
     Created = "Created",
@@ -113,6 +117,10 @@ export interface AgentExecution {
     completedMs?: number;
     /** Optional error message if execution failed */
     error?: string;
+    /** The agent-state task this execution works on, when it was created for one. */
+    taskId?: string;
+    /** Why the execution was cancelled (status `Cancelled`). */
+    cancelReason?: string;
     /** Metadata about the execution */
     metadata?: Record<string, any>;
 }
@@ -120,6 +128,7 @@ export interface AgentExecution {
  * Parse an agent reference from its canonical form
  * @example parseAgentRef("flow://agent/researcher@1")
  */
+export declare const AGENT_EXECUTION_TERMINAL_STATUSES: readonly AgentExecutionStatus[];
 export declare function parseAgentRef(ref: string): AgentRef;
 /**
  * Create an agent reference

package/dist/agent.d.ts.map

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

package/dist/agent.js

@@ -6,7 +6,11 @@
  * of the same causal graph.
  */
 /**
- * Lifecycle states for agent execution
+ * Lifecycle states for agent execution.
+ *
+ * `Completed`, `Failed` and `Cancelled` are terminal. `Cancelled` is reachable
+ * from every non-terminal state, through `AgentRuntime.cancel` or
+ * `transition(execution, Cancelled)`.
  */
 export var AgentExecutionStatus;
 (function (AgentExecutionStatus) {
@@ -25,6 +29,11 @@ export var AgentExecutionStatus;
  * Parse an agent reference from its canonical form
  * @example parseAgentRef("flow://agent/researcher@1")
  */
+export const AGENT_EXECUTION_TERMINAL_STATUSES = [
+    AgentExecutionStatus.Completed,
+    AgentExecutionStatus.Failed,
+    AgentExecutionStatus.Cancelled,
+];
 export function parseAgentRef(ref) {
     const match = ref.match(/^flow:\/\/agent\/([^@]+)@(\d+)$/);
     if (!match) {

package/dist/build-identity.json

@@ -1,13 +1,13 @@
 {
   "schema": "feltdb.build-identity.v2",
   "package": "@feltdb/core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "git": {
-    "sha1": "b67312f73ea647ffea6f87337303c170d40d541d",
+    "sha1": "5ad54972a9e31a5459cadbb471428111624ec9c6",
     "dirty": false
   },
   "path_in_vcs": "packages/core",
-  "source_digest": "sha256:7435af3423598673fcce76eb77444ee1e160f39f3fd83a0a788517e315bd3444",
+  "source_digest": "sha256:01efc5737aae1fef37c976e5841df3bb9b615d034f31d27b038f7fd4ca202428",
   "inputs": [
     "Cargo.lock",
     "Cargo.toml",
@@ -20,7 +20,7 @@
     "tools/cli",
     "tools/create-feltdb"
   ],
-  "files": 776,
+  "files": 789,
   "build": {
     "command": "npm run build",
     "node": "v24.9.0"

package/dist/cli/commands.js

@@ -40,6 +40,27 @@ function loadProjectEnvironment(file = path.resolve('.env.local')) {
         if (!(key in process.env))
             process.env[key] = value;
     }
+    warnBrowserExposedCredentials();
+}
+/**
+ * Credentials under a `VITE_` name are inlined into the application's browser
+ * bundle by Vite, so they are no longer read as credentials anywhere. Say so,
+ * rather than silently dropping authentication a project used to have.
+ */
+function warnBrowserExposedCredentials() {
+    for (const name of Object.keys(process.env)) {
+        if (/^VITE_[A-Z0-9_]*(?:TOKEN|API_KEY|SECRET)$/.test(name) && process.env[name]) {
+            console.warn(`⚠ ${name} is ignored: VITE_* variables are inlined into browser bundles. Move the credential to FELTDB_TOKEN (server-side only).`);
+        }
+    }
+}
+/**
+ * The local `feltdb dev` Studio is an operator console on localhost. It
+ * receives the developer's server-side key at runtime (no-store), never from a
+ * bundled VITE_* value.
+ */
+function studioOperatorToken() {
+    return process.env.FELTDB_TOKEN || '';
 }
 async function availablePort(preferred, host = '127.0.0.1') {
     for (let port = preferred; port < preferred + 100; port += 1) {
@@ -831,8 +852,8 @@ async function handleConnect(args) {
     let health;
     try {
         const response = await fetch(`${url}/health`, {
-            headers: process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY
-                ? { Authorization: `Bearer ${process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY}` }
+            headers: process.env.FELTDB_TOKEN
+                ? { Authorization: `Bearer ${process.env.FELTDB_TOKEN}` }
                 : {},
             signal: controller.signal,
         });
@@ -855,14 +876,14 @@ async function handleConnect(args) {
     fs.writeFileSync(connFile, JSON.stringify({
         url,
         connected: new Date().toISOString(),
-        authenticated: Boolean(process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY),
+        authenticated: Boolean(process.env.FELTDB_TOKEN),
         namespace: managed.namespace || project.namespace || 'default',
         runtime: project.runtime || 'self-hosted',
     }, null, 2));
     console.log('✅ Connected to FeltDB\n');
     console.log('Endpoint:     ' + url);
     console.log(`Namespace:    ${managed.namespace || project.namespace || 'default'}`);
-    console.log(`Authenticated: ${process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY ? 'yes' : 'no'}`);
+    console.log(`Authenticated: ${process.env.FELTDB_TOKEN ? 'yes' : 'no'}`);
     console.log(`Runtime:      ${project.runtime || 'self-hosted'}`);
     console.log(`Health:       ${health.status || 'healthy'}\n`);
     console.log('Use: feltdb status  (to check connection)\n');
@@ -1894,7 +1915,7 @@ async function handleStudio(args, onReady) {
                 environment: managedProject.environment || 'production',
                 publishEndpoint: '/_feltdb/publish',
             } : undefined;
-            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '', managedPublish, session, studioQuery, sourceSync: { enabled: true, webllmEnabled, previewOnly, token: studioMutationToken, aiModel: publicAiModelConfiguration() } }));
+            response.end(JSON.stringify({ token: connectUrl ? studioOperatorToken() : '', managedPublish, session, studioQuery, sourceSync: { enabled: true, webllmEnabled, previewOnly, token: studioMutationToken, aiModel: publicAiModelConfiguration() } }));
             return;
         }
         if (pathname === '/_feltdb/contract') {
@@ -1913,7 +1934,7 @@ async function handleStudio(args, onReady) {
                         endpoint.searchParams.set('application_id', applicationId);
                         endpoint.searchParams.set('environment', managedProject.environment || lastPublished?.environment || 'production');
                         const headers = {};
-                        const credential = process.env.FELTDB_MANAGED_CONTROL_API_KEY || process.env.VITE_FELTDB_API_KEY;
+                        const credential = process.env.FELTDB_MANAGED_CONTROL_API_KEY || process.env.FELTDB_TOKEN;
                         if (credential)
                             headers.authorization = `Bearer ${credential}`;
                         const discovered = await fetch(endpoint, { headers });

package/dist/collection.d.ts

@@ -359,7 +359,9 @@ export declare class Collection<T> {
     /**
      * Refresh data from the database and notify subscribers.
      */
-    refresh(): Promise<void>;
+    refresh(options?: {
+        strict?: boolean;
+    }): Promise<void>;
 }
 /**
  * Relationship helper for loading related data.

package/dist/collection.d.ts.map

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

package/dist/collection.js

@@ -129,7 +129,9 @@ export class Collection {
      * Returns cached results (live-updated).
      */
     async all() {
-        await this.refresh();
+        // A read the authority refused, or could not answer, is raised typed --
+        // never answered from whatever this handle last cached.
+        await this.refresh({ strict: true });
         return [...this.cache];
     }
     /** List records through the canonical application collection API. */
@@ -375,7 +377,7 @@ export class Collection {
         const key = `${this.name}:${id}`;
         const result = await this.db.get(key);
         if (!result.success) {
-            throw new Error(result.error || `Failed to read record ${id}`);
+            throw runtimeFailure(result, result.error || `Failed to read record ${id}`);
         }
         if (result.data) {
             return JSON.parse(result.data);
@@ -421,7 +423,7 @@ export class Collection {
             const stored = { ...data, id: recordId, __version: 1 };
             const result = await this.db.insert(key, JSON.stringify(stored));
             if (!result.success) {
-                throw new Error(`Insert failed: ${result.error}`);
+                throw runtimeFailure(result, `Insert failed: ${result.error}`);
             }
             await this.publish('insert', key, String(recordId), null, stored);
             return String(recordId);
@@ -614,9 +616,11 @@ export class Collection {
         const result = await this.db.delete(key);
         if (!result.success) {
             const message = `Delete failed: ${result.error}`;
-            throw /not found/i.test(String(result.error))
-                ? new FeltDBServiceError(message, FeltDBErrorCode.NOT_FOUND)
-                : new Error(message);
+            throw result.cause
+                ? runtimeFailure(result, message)
+                : /not found/i.test(String(result.error))
+                    ? new FeltDBServiceError(message, FeltDBErrorCode.NOT_FOUND)
+                    : new Error(message);
         }
         // Update indexes - find and remove the deleted record
         const deleted = await this.get(id);
@@ -686,7 +690,7 @@ export class Collection {
                 throw error;
             const existing = await this.db.get(key);
             if (!existing.success) {
-                throw new Error(existing.error || `could not read the record that won ${key}`);
+                throw runtimeFailure(existing, existing.error || `could not read the record that won ${key}`);
             }
             if (!existing.data) {
                 throw new Error(`${key} was created and then removed while resolving a conditional create`);
@@ -914,7 +918,7 @@ export class Collection {
     /**
      * Refresh data from the database and notify subscribers.
      */
-    async refresh() {
+    async refresh(options = {}) {
         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
@@ -980,14 +984,32 @@ export class Collection {
                 }
             }
             else if (!result.success) {
+                if (options.strict)
+                    throw runtimeFailure(result, result.error || `Failed to read ${this.name}`);
                 console.error('Query failed:', result.error);
             }
         }
         catch (err) {
+            if (options.strict)
+                throw err;
             console.error('Refresh error:', err);
         }
     }
 }
+/**
+ * The error a failed runtime result is raised as. A remote runtime attaches
+ * the authority's typed refusal (`cause`): its stable code, status, request id
+ * and body travel on, so an unauthenticated, cross-application or interrupted
+ * operation is never a bare `Error` with the code only in its message.
+ */
+function runtimeFailure(result, message) {
+    const cause = result.cause;
+    if (!(cause instanceof FeltDBServiceError))
+        return new Error(message);
+    const error = new FeltDBServiceError(message, cause.code, cause.requestId, cause.status, cause.body);
+    error.cause = cause;
+    return error;
+}
 /**
  * Relationship helper for loading related data.
  */

package/dist/create/build-identity.json

@@ -1,13 +1,13 @@
 {
   "schema": "feltdb.build-identity.v2",
   "package": "create-feltdb",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "git": {
-    "sha1": "b67312f73ea647ffea6f87337303c170d40d541d",
+    "sha1": "5ad54972a9e31a5459cadbb471428111624ec9c6",
     "dirty": false
   },
   "path_in_vcs": "tools/create-feltdb",
-  "source_digest": "sha256:7435af3423598673fcce76eb77444ee1e160f39f3fd83a0a788517e315bd3444",
+  "source_digest": "sha256:01efc5737aae1fef37c976e5841df3bb9b615d034f31d27b038f7fd4ca202428",
   "inputs": [
     "Cargo.lock",
     "Cargo.toml",
@@ -20,7 +20,7 @@
     "tools/cli",
     "tools/create-feltdb"
   ],
-  "files": 776,
+  "files": 789,
   "build": {
     "command": "npm run build",
     "node": "v24.9.0"

package/dist/create/cli.js

@@ -226,7 +226,7 @@ Deployment Target (Explicit):
 
   --managed               Managed FeltDB runtime
                           Best for: Production without operating servers
-                          Requires VITE_FELTDB_URL and VITE_FELTDB_API_KEY
+                          Requires VITE_FELTDB_URL; server-side FELTDB_TOKEN only
 
 Options:
   --browser                Explicit: Browser runtime with IndexedDB