@feltdb/core 0.12.2 → 0.15.0

package/dist/create/server-source/crates/feltdb-server/tests/transaction_precondition_contract.rs

@@ -0,0 +1,403 @@
+//! The transaction-precondition contract through the Rust client (`feltdb-client`) against this
+//! crate's real server binary, over both transaction routes.
+//!
+//! The same contract is held for the TypeScript SDK by
+//! `e2e/transaction-precondition-contract.test.mjs`. Every test stages the failure the contract
+//! forbids and asserts the authority's structured answer as the Rust client decodes it.
+
+use std::{
+    io::{BufRead, BufReader},
+    path::PathBuf,
+    process::{Child, Command, Stdio},
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use feltdb_client::{
+    path_segment, AppTransaction, Client, Error, Method, Operation, Precondition,
+    PreconditionFailure, Transaction,
+};
+use serde_json::{json, Value};
+
+struct Server {
+    child: Child,
+    url: String,
+    directory: PathBuf,
+}
+
+impl Server {
+    fn start(name: &str) -> Self {
+        let directory = std::env::temp_dir().join(format!(
+            "feltdb-txp-{name}-{}-{}",
+            std::process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&directory).unwrap();
+        let data = directory.join("feltdb.log");
+        let mut child = Command::new(env!("CARGO_BIN_EXE_feltdb-server"))
+            .args([
+                "--host",
+                "127.0.0.1",
+                "--port",
+                "0",
+                "--namespace",
+                "txp",
+                "--data",
+                data.to_str().unwrap(),
+                "--keys",
+                directory.join("keys.json").to_str().unwrap(),
+                "--audit",
+                directory.join("audit.log").to_str().unwrap(),
+            ])
+            .env("FELTDB_MASTER_KEY", "txp-development-key")
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .unwrap();
+        let mut lines = BufReader::new(child.stdout.take().unwrap()).lines();
+        let url = loop {
+            let line = lines
+                .next()
+                .expect("server exited before readiness")
+                .unwrap();
+            if let Some(rest) = line.split("ready at ").nth(1) {
+                break rest.split_whitespace().next().unwrap().to_owned();
+            }
+        };
+        std::thread::spawn(move || lines.for_each(drop));
+        Self {
+            child,
+            url,
+            directory,
+        }
+    }
+
+    fn client(&self) -> Client {
+        Client::builder(&self.url).build().unwrap()
+    }
+
+    fn data(&self) -> PathBuf {
+        self.directory.join("feltdb.log")
+    }
+}
+
+impl Drop for Server {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+        let _ = std::fs::remove_dir_all(&self.directory);
+    }
+}
+
+/// Provision one application with collections `A` and `B` and return its id.
+async fn provision(client: &Client) -> String {
+    let tenant = client
+        .request(
+            Method::POST,
+            "/api/tenants",
+            Some(&json!({ "name": "txp" })),
+        )
+        .await
+        .unwrap();
+    let tenant_id = tenant["tenant_id"]
+        .as_str()
+        .or(tenant["id"].as_str())
+        .unwrap();
+    let application = client
+        .request(
+            Method::POST,
+            &format!("/api/tenants/{tenant_id}/applications"),
+            Some(&json!({ "name": "txp" })),
+        )
+        .await
+        .unwrap();
+    let application_id = application["application_id"]
+        .as_str()
+        .or(application["id"].as_str())
+        .unwrap()
+        .to_owned();
+    let drafts = format!("/api/applications/{application_id}/drafts");
+    let draft = client
+        .request(Method::POST, &drafts, Some(&json!({})))
+        .await
+        .unwrap();
+    let draft_id = draft["draft_id"].as_str().unwrap();
+    let mut manifest = draft["manifest"].clone();
+    let fields = json!([{ "name": "n", "type": "integer", "required": false }]);
+    manifest["collections"] = json!([
+        { "name": "A", "fields": fields },
+        { "name": "B", "fields": fields },
+    ]);
+    manifest["policies"] = json!(
+        ["A", "B"].map(|name| json!({ "name": name, "resource": name,
+        "read": "authenticated", "write": "authenticated", "capabilities": [] }))
+    );
+    let version = draft["version"].as_u64().unwrap().to_string();
+    client
+        .request_with_headers(
+            Method::PUT,
+            &format!("{drafts}/{draft_id}"),
+            &[("if-version", &version)],
+            Some(&json!({ "manifest": manifest })),
+        )
+        .await
+        .unwrap();
+    let revision = client
+        .request(
+            Method::POST,
+            &format!("{drafts}/{draft_id}/commit"),
+            Some(&json!({})),
+        )
+        .await
+        .unwrap();
+    let encoded = path_segment(revision["revision_id"].as_str().unwrap());
+    client
+        .request(
+            Method::POST,
+            &format!("/api/applications/{application_id}/revisions/{encoded}/promote"),
+            Some(&json!({ "environment": "production", "reason": "txp" })),
+        )
+        .await
+        .unwrap();
+    application_id
+}
+
+fn failure_body(error: &Error) -> Value {
+    match error {
+        Error::Api(api) => api.body["failure"].clone(),
+        other => panic!("expected an API refusal, got {other}"),
+    }
+}
+
+#[tokio::test]
+async fn direct_route_a_stale_guard_refuses_every_staged_write_with_a_structured_failure() {
+    let server = Server::start("direct-stale");
+    let client = server.client();
+    client
+        .commit(&Transaction::generated().operation(Operation::create("A", "a", json!({}))))
+        .await
+        .unwrap();
+    client
+        .commit(&Transaction::generated().operation(Operation::create("B", "b", json!({ "n": 1 }))))
+        .await
+        .unwrap();
+    // Another writer advances A from 1 to 2.
+    client
+        .commit(
+            &Transaction::generated()
+                .operation(Operation::put("A", "a", json!({ "n": 2 })).expect_version(1)),
+        )
+        .await
+        .unwrap();
+    let refused = client
+        .commit(
+            &Transaction::generated()
+                .precondition(Precondition::version("A", "a", 1))
+                .operation(Operation::put("A", "a", json!({ "n": 9 })))
+                .operation(Operation::put("B", "b", json!({ "n": 9 }))),
+        )
+        .await
+        .unwrap_err();
+    assert_eq!(refused.code(), Some("PRECONDITION_FAILED"));
+    assert_eq!(refused.status(), Some(409));
+    assert_eq!(
+        refused.precondition_failure(),
+        Some(&PreconditionFailure::Version {
+            collection: "A".into(),
+            key: "A:a".into(),
+            expected: 1,
+            actual: 2
+        })
+    );
+    assert_eq!(
+        failure_body(&refused)["id"],
+        "a",
+        "the failure names the record id"
+    );
+    assert_eq!(
+        client.get("B", "b").await.unwrap().unwrap().value["n"],
+        1,
+        "B is unchanged"
+    );
+}
+
+#[tokio::test]
+async fn application_route_refusals_name_the_public_collection_and_record() {
+    let server = Server::start("app-shape");
+    let client = server.client();
+    let app = client.application(&provision(&client).await);
+    app.commit(
+        &AppTransaction::generated()
+            .insert("A", "a", json!({ "n": 1 }))
+            .insert("B", "b", json!({ "n": 1 })),
+    )
+    .await
+    .unwrap();
+    // `__version` is the document version the authority owns: 1 on create, 2 after a fenced write.
+    app.commit(
+        &AppTransaction::generated()
+            .expect_version("A", "a", 1)
+            .update("A", "a", json!({ "n": 2 })),
+    )
+    .await
+    .unwrap();
+
+    let stale = app
+        .commit(
+            &AppTransaction::generated()
+                .expect_version("A", "a", 1)
+                .update("A", "a", json!({ "n": 9 }))
+                .update("B", "b", json!({ "n": 9 })),
+        )
+        .await
+        .unwrap_err();
+    assert_eq!(stale.code(), Some("PRECONDITION_FAILED"), "{stale}");
+    assert_eq!(
+        stale.precondition_failure(),
+        Some(&PreconditionFailure::Version {
+            collection: "A".into(),
+            key: "A:a".into(),
+            expected: 1,
+            actual: 2
+        }),
+        "the refusal names the application's collection, not the authority's storage namespace: {}",
+        failure_body(&stale)
+    );
+    assert_eq!(failure_body(&stale)["id"], "a");
+
+    // A create of a record that exists is the same structured refusal on every route.
+    let present = app
+        .commit(&AppTransaction::generated().insert("A", "a", json!({ "n": 1 })))
+        .await
+        .unwrap_err();
+    assert_eq!(present.code(), Some("PRECONDITION_FAILED"), "{present}");
+    assert!(
+        matches!(
+            present.precondition_failure(),
+            Some(PreconditionFailure::Present { collection, key }) if collection == "A" && key == "A:a"
+        ),
+        "{present}: {}",
+        failure_body(&present)
+    );
+}
+
+#[tokio::test]
+async fn application_route_concurrent_writers_from_one_version_exactly_one_commits() {
+    let server = Server::start("app-race");
+    let client = server.client();
+    let application_id = provision(&client).await;
+    let app = client.application(&application_id);
+    app.commit(&AppTransaction::generated().insert("A", "a", json!({ "n": 0 })))
+        .await
+        .unwrap();
+    for round in 0..20u64 {
+        let from = round + 1;
+        let contenders = (0..6u64).map(|index| {
+            let app = server.client().application(&application_id);
+            tokio::spawn(async move {
+                app.commit(
+                    &AppTransaction::generated()
+                        .expect_version("A", "a", from)
+                        .update("A", "a", json!({ "n": index }))
+                        .insert("B", format!("b-{round}-{index}"), json!({ "n": index })),
+                )
+                .await
+            })
+        });
+        let outcomes: Vec<_> = futures_join(contenders).await;
+        let winners = outcomes.iter().filter(|outcome| outcome.is_ok()).count();
+        assert_eq!(winners, 1, "round {round}: {winners} winners");
+        for loser in outcomes.iter().filter_map(|outcome| outcome.as_ref().err()) {
+            assert!(
+                matches!(
+                    loser.precondition_failure(),
+                    Some(PreconditionFailure::Version { expected, actual, .. }) if *expected == from && *actual == from + 1
+                ),
+                "round {round}: {loser}"
+            );
+        }
+    }
+}
+
+async fn futures_join<T: Send + 'static>(
+    handles: impl Iterator<Item = tokio::task::JoinHandle<T>>,
+) -> Vec<T> {
+    let mut outcomes = Vec::new();
+    for handle in handles.collect::<Vec<_>>() {
+        outcomes.push(handle.await.unwrap());
+    }
+    outcomes
+}
+
+#[tokio::test]
+async fn application_route_a_duplicate_reports_the_original_commit() {
+    let server = Server::start("app-duplicate");
+    let client = server.client();
+    let app = client.application(&provision(&client).await);
+    let original = AppTransaction::new("txp-dup").insert("A", "a", json!({ "n": 1 }));
+    let first = app.commit(&original).await.unwrap();
+    app.commit(&AppTransaction::generated().insert("B", "b", json!({ "n": 1 })))
+        .await
+        .unwrap();
+    let replay = app.commit(&original).await.unwrap();
+    assert!(replay.result.duplicate);
+    assert_eq!(replay.result.commit_revision, first.result.commit_revision);
+    assert_eq!(replay.result.base_revision, first.result.base_revision);
+    assert_eq!(replay.result.state_after, first.result.state_after);
+    let different = app
+        .commit(&AppTransaction::new("txp-dup").insert("A", "other", json!({ "n": 1 })))
+        .await
+        .unwrap_err();
+    assert_eq!(different.code(), Some("IDEMPOTENCY_CONFLICT"));
+}
+
+#[tokio::test]
+async fn a_storage_failure_at_commit_is_a_durability_failure_not_a_conflict() {
+    let server = Server::start("direct-storage");
+    let client = server.client();
+    client
+        .commit(&Transaction::generated().operation(Operation::create("A", "a", json!({}))))
+        .await
+        .unwrap();
+    // The next append opens a directory and fails before writing anything.
+    let aside = server.data().with_extension("aside");
+    std::fs::rename(server.data(), &aside).unwrap();
+    std::fs::create_dir(server.data()).unwrap();
+    let refused = client
+        .commit(&Transaction::generated().operation(Operation::create("A", "b", json!({}))))
+        .await
+        .unwrap_err();
+    std::fs::remove_dir(server.data()).unwrap();
+    std::fs::rename(&aside, server.data()).unwrap();
+    assert!(
+        !refused.is_conflict(),
+        "a storage failure was reported as a lost race: {refused}"
+    );
+    assert_eq!(refused.code(), Some("DURABILITY_FAILURE"), "{refused}");
+    assert_eq!(refused.status(), Some(503));
+}
+
+#[tokio::test]
+async fn a_write_whose_answer_never_arrives_is_outcome_unknown() {
+    // A listener that accepts and never answers: the request is sent, no answer arrives.
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let address = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        let mut held = Vec::new();
+        while let Ok((socket, _)) = listener.accept().await {
+            held.push(socket);
+        }
+    });
+    let client = Client::builder(format!("http://{address}"))
+        .timeout(Duration::from_millis(300))
+        .build()
+        .unwrap();
+    let error = client
+        .commit(&Transaction::new("txp-unknown").operation(Operation::create("A", "a", json!({}))))
+        .await
+        .unwrap_err();
+    assert!(error.is_outcome_unknown(), "{error}");
+    assert!(!error.is_conflict());
+}

package/dist/create/setup-summary.js

@@ -0,0 +1,40 @@
+/**
+ * What `create-feltdb` will generate, in the words the developer chose it in.
+ *
+ * The summary is printed before anything is written, so it must describe the
+ * project that is about to exist — not the menu that produced it. Each line
+ * states what is included and what it needs; nothing here claims a capability
+ * the resulting instance would not provide.
+ */
+export const RUNTIME_CHOICES = [
+    { value: 'browser', label: 'Browser', summary: 'data stays in the browser (IndexedDB); nothing else to run' },
+    { value: 'node', label: 'Node.js authority', summary: 'data lives in a FeltDB authority the application connects to; `feltdb dev` runs one locally' },
+    { value: 'self-hosted', label: 'Self-hosted server', summary: 'data lives in your own feltdb-server; Docker Compose included' },
+    { value: 'managed', label: 'Managed', summary: 'data lives in FeltDB-hosted infrastructure; needs a FeltDB account' },
+];
+/** The React starter's tour includes its assistants; only the vanilla template makes them optional. */
+export function agentsIncluded(options) {
+    return options.framework === 'react' || options.agents;
+}
+export function describeSetup(options) {
+    const runtime = RUNTIME_CHOICES.find(choice => choice.value === options.runtime);
+    const lines = [
+        `Data:          ${runtime ? `${runtime.label} — ${runtime.summary}` : options.runtime}`,
+        `Framework:     ${options.framework === 'react' ? 'React' : 'Vanilla TypeScript'}`,
+    ];
+    if (options.framework === 'react') {
+        lines.push('Starter:       sign-up, projects, invitations, activity, and two assistants that run bounded capabilities (no AI model needed)');
+        lines.push('Capabilities:  declared in feltdb.flow (ProjectSearch, ProjectSummary, ActivitySummary)');
+    }
+    else {
+        lines.push(`Agents:        ${options.agents ? 'example included' : 'not included'}`);
+        lines.push(`Capabilities:  ${options.capabilities}`);
+    }
+    lines.push(options.webllm
+        ? 'AI builder:    included — @feltdb/webllm; downloads a small language model (a few hundred MB) into the browser on first use and needs WebGPU'
+        : 'AI builder:    not included (add later: npm install @feltdb/webllm)');
+    if (options.distributed) {
+        lines.push('Distributed:   recorded in feltdb.config.json; it takes effect when you deploy several feltdb-server nodes. Development runs one local authority.');
+    }
+    return lines;
+}

package/dist/db.d.ts

@@ -11,7 +11,7 @@ import { type TransactionReadBasis, type TransactionReadSet, type AtomicTransact
 import { type Cell } from './cell.js';
 import type { AgentRef, AgentDefinition, AgentExecution } from './agent.js';
 import { AgentRegistry } from './agent-registry.js';
-import { AgentRuntime } from './agent-runtime.js';
+import { AgentRuntime, type CreateAgentExecutionOptions, type FindAgentExecutionQuery } from './agent-runtime.js';
 import type { AuthorityQueryPage, AuthorityQueryRequest } from './http-db.js';
 import type { EmbeddedQueryExplanation } from './embedded-query.js';
 import { type FeltDBArchitectureInvariantService } from './architecture-invariant.js';
@@ -38,9 +38,25 @@ export interface FeltDBOptions extends FeltDBDeploymentConfig {
         applicationId?: string;
         environment?: string;
         requestTimeoutMs?: number;
+        /**
+         * Operator consoles only (FeltDB Studio): a human pastes their own service
+         * key into their own browser tab at runtime. Applications must never set
+         * this — a service key in an application's browser code is published to
+         * every visitor. Without it, a `fdb_live_` key in a browser runtime throws
+         * `FeltDBBrowserCredentialError`.
+         */
+        operatorConsole?: true;
     };
     memory?: true;
     browser?: true;
+    /**
+     * Local file runtime only. `exclusive` (default): this process owns the
+     * state directory; another process opening it is refused with
+     * `LocalStateLockedError` (`STATE_LOCKED`) until `db.close()` or exit.
+     * `shared`: several processes may open the directory at once (each commit
+     * is still atomic and serialized); use it for multi-process workers.
+     */
+    access?: 'exclusive' | 'shared';
     /** Explicit durable authority. Omitted only for legacy unscoped clients. */
     authorityScope?: AuthorityScope;
 }
@@ -77,6 +93,8 @@ export interface FeltDBRuntimeCapabilities {
     replication: boolean;
     remoteAuthority: boolean;
     offline: boolean;
+    /** `storeContent` / `acquireContent` are available. */
+    content: boolean;
 }
 export interface FeltDBCapabilitySurface {
     (): FeltDBRuntimeCapabilities;
@@ -249,10 +267,6 @@ export interface RuntimeDiagnostics {
         message: string;
     }>;
 }
-/**
- * State-first database interface.
- * Applications use this to treat FeltDB collections as live application state.
- */
 export declare class StateFirstDB {
     private jsDb;
     private collections;
@@ -287,10 +301,24 @@ export declare class StateFirstDB {
             idempotencyKey?: string;
         }) => Promise<unknown>;
     };
+    /**
+     * Start an agent run. It completes only when `completion` — criteria the
+     * server checks against the result it observed — holds; without it the run
+     * executes but ends `failed` with `COMPLETION_UNVERIFIABLE`.
+     */
     readonly agents: {
         run: (name: string, input?: unknown, options?: {
             idempotencyKey?: string;
             goal?: string;
+            completion?: {
+                kind: "result_count";
+                min: number;
+                max?: number;
+            } | {
+                kind: "result_contains";
+                field: string;
+                equals: unknown;
+            };
         }) => Promise<unknown>;
     };
     readonly capabilities: FeltDBCapabilitySurface;
@@ -431,6 +459,17 @@ export declare class StateFirstDB {
      * transactions. Runtimes that cannot refuse rather than silently degrading
      * the transaction into a sequence of independent writes.
      */
+    /**
+     * Tell this process's live collections that a transaction committed.
+     *
+     * Collection writes publish through the reactive dependency graph; a
+     * transaction bypasses the collection, so without this a subscriber on the
+     * local file or memory runtime never learns about it. The announcement is
+     * a notification only (subscribers re-read committed state), and it runs
+     * after the commit is durable: a failing subscriber cannot turn a committed
+     * transaction into a reported failure.
+     */
+    private announceCommittedTransaction;
     transaction(build: ((tx: AtomicTransactionScope) => void | Promise<void>) | AtomicTransactionDocument, options?: AtomicTransactionOptions): Promise<AtomicTransactionResult>;
     /**
      * Capture a read basis: what the authority holds, now, for a set of records
@@ -498,14 +537,28 @@ export declare class StateFirstDB {
     }>;
     /** Inspect the causal operation that currently materializes a remote record. */
     recordProvenance(collection: string, id: string): Promise<any>;
-    /** Persist immutable content by hash; repeated bytes deduplicate automatically. */
+    /**
+     * Persist immutable content by its SHA-256; repeated bytes deduplicate.
+     * Returns `{ hash, bytes, ref: 'sha256:<hash>' }`.
+     *
+     * A server runtime stores it in the server's content store; the local file
+     * runtime stores it under its state directory (`content/<hash>`), durably
+     * before this returns. Memory and browser runtimes refuse with
+     * `CONTRACT_UNSUPPORTED`.
+     */
     storeContent(content: Uint8Array): Promise<{
         hash: string;
         bytes: number;
         ref: string;
     }>;
-    /** Resolve verified immutable content locally or from configured peers. */
+    /**
+     * Resolve content by hash: verified against its SHA-256 before it is
+     * returned (`CONTENT_INTEGRITY_FAILURE` otherwise), `null` when absent. A
+     * server also asks its configured peers; the local runtime reads its own
+     * directory only.
+     */
     acquireContent(hash: string): Promise<Uint8Array | null>;
+    private contentUnsupported;
     /** Define a durable workflow whose lifecycle is ordinary replicated state. */
     defineWorkflow(name: string, steps: string[]): Promise<any>;
     startWorkflow(name: string, input?: unknown): Promise<any>;
@@ -513,7 +566,19 @@ export declare class StateFirstDB {
     completeWorkflowStep(runId: string, step: string, claimId: string, result?: unknown): Promise<any>;
     /** Define and start state-first agents; workers observe and advance these records externally. */
     defineStateAgent(name: string, capabilities?: string[], constraints?: unknown): Promise<any>;
-    startStateAgent(name: string, goal: string, input?: unknown): Promise<any>;
+    /**
+     * `completion` is what the server must observe for the run to complete; a
+     * run without it never completes. See the agent-run section of the public API contract.
+     */
+    startStateAgent(name: string, goal: string, input?: unknown, completion?: {
+        kind: 'result_count';
+        min: number;
+        max?: number;
+    } | {
+        kind: 'result_contains';
+        field: string;
+        equals: unknown;
+    }): Promise<any>;
     /**
      * Define an agent with declarative configuration.
      *
@@ -546,16 +611,32 @@ export declare class StateFirstDB {
      */
     getAgentRuntime(): AgentRuntime;
     /**
-     * Create an agent execution
+     * Create an agent execution. It is committed to `_flow_agent_executions`
+     * before this returns; pass `taskId` to find it later with
+     * `findAgentExecution({ taskId })`.
      */
-    createAgentExecution(agentRef: AgentRef, goal: string, inputs: string[]): Promise<AgentExecution>;
+    createAgentExecution(agentRef: AgentRef, goal: string, inputs: string[], options?: CreateAgentExecutionOptions): Promise<AgentExecution>;
     private agentExecutionRecord;
+    private agentExecutionIndexesDeclared;
+    /** Declare the lookup indexes once per handle, on an embedded runtime only. */
+    private declareAgentExecutionIndexes;
+    private queryAgentExecution;
+    /**
+     * The most recently created execution for an agent-state task or an agent,
+     * read from durable state through a declared index (one bounded query; it
+     * never scans `_flow_agent_executions`). Null when there is none.
+     */
+    findAgentExecution(query: FindAgentExecutionQuery): Promise<AgentExecution | null>;
     /** Claim and durably materialize an embedded agent execution. */
     startAgentExecution(execution: AgentExecution, peerId?: string): Promise<void>;
     /** Advance an agent lifecycle and expose the transition as ordinary state. */
     transitionAgentExecution(execution: AgentExecution, status: import('./agent.js').AgentExecutionStatus): Promise<void>;
+    /** Resume an execution for `peerId` (status `Observing`), committed before this returns. */
+    resumeAgentExecution(execution: AgentExecution, peerId?: string): Promise<void>;
     completeAgentExecution(execution: AgentExecution, resultRef: string): Promise<void>;
     failAgentExecution(execution: AgentExecution, error: string): Promise<void>;
+    /** Cancel a non-terminal execution (terminal status `Cancelled`), committed before this returns. */
+    cancelAgentExecution(execution: AgentExecution, reason?: string): Promise<void>;
     /**
      * Close the database and clean up resources.
      */