Every seed. Every edge.

Choose the right seed packet.

This is the public SDK surface, with the behavior that matters when code reaches a durable database. Flower is unreleased; APIs, storage formats, and wire contracts may change without backward compatibility.

npm install @flower-js/sdk
npx flower --help

Browse the SDK source on GitHub. The server is a separate Rust executable and needs no Node process. The SDK requires Node 22.18+ for its CLI and Node-only tools. Inside this repository, run npm ci and npm run build before using the package’s own imports. A checkout’s server is ./target/release/flower; npx flower is the SDK command, not the server.

Values, identity, and purity.

QuickJS supports more JavaScript values than Flower stores. BigInt, Map, Set, Date, typed arrays, and class instances do not cross the database/HTTP boundary automatically. Encode them explicitly as JSON, such as decimal strings with a versioned tag. Numbers outside JavaScript’s exact integer range remain floating-point numbers; use safe integer units where exact arithmetic is required.

Callbacks are synchronous. Return a finite JSON value, including explicit null for “nothing”; do not return a Promise or undefined. No filesystem, network, Node globals, timers or ambient wall clock is available inside application callbacks. Explicit native crypto capabilities provide mutation-only application randomness; shared-key handles are opaque invocation-local capabilities with no observable random token, as described below. Use ctx.now() for database time and external workers for effects. Each callback starts from an isolated QuickJS/Wasm image. Mutating module globals cannot create durable state or communicate with another callback.

The compiled module and Wasmtime image are reused, while guest heaps are isolated. Rust owns records, indexes, dependency tracking, staging, and Raft application. More expensive callbacks, large results, nested derived evaluations, and broad scans still cost CPU and memory; isolation does not make arbitrary functions incremental.

Collections, equality, and ordered scans.

import { collection, define, query } from "@flower-js/sdk";

const orders = collection<{ tenant: string; state: string; cents: number }>("orders")
  .index("byTenantState", ["tenant", "state"]);
const pending = query("orders.pending", (ctx, tenant: string) =>
  ctx.query(orders.by("byTenantState").eq([tenant, "pending"])));

export default define({ collections: [orders], http: { pending } });

Include indexed collections in define({ collections }) to maintain durable indexes. Omitting a collection keeps scan-based query behavior. Indexes support JSON equality and ordered scalar ranges; they do not enforce uniqueness constraints or arbitrary projections. Missing fields do not match null. Object key order does not change equality. Results retain source-key order, including Unicode keys.

For a due timer index ["state", "dueAt"], use ctx.range(timers.by("due").range({prefix: ["pending"], lte: ctx.now(), limit: 1})). Empty ranges also track phantom dependencies. This implementation conservatively invalidates all ordered readers of an index when any scalar-indexed row changes, including value-only updates; it does not yet track exact intervals.

Rows and index entries commit together. Queries inside mutations see staged writes. Derived equality queries depend on the matching bucket and records: inserting into an empty bucket invalidates its readers; unrelated buckets do not. Direct deployment backfills added indexes and removes dropped entries in one candidate under normal budgets. For durable bounded progress, use staged deployment; operators explicitly advance pages and activate the result, with no automatic background backfill. See index and reducer operation details.

What application code can do.

Clock-independent query results can be reused across unrelated revisions when their dependency certificates remain valid. Certificates cover point reads (including absence), collection/index membership, returned indexed rows, derived outcomes, and code/schema/managed-policy identities. Fresh hits still require the normal quorum fence; every public hit still runs authorization and keys by the complete principal. Time and managed-crypto dependencies remain uncacheable. Certificate memory shares the query cache budget and does not retain old JSON payloads. FLOWER_QUERY_CACHE_BYTES defaults to 16 MiB per logical database; FLOWER_QUERY_FLIGHT_BYTES defaults to 512 KiB for concurrent shared-evaluation metadata. Zero disables either optimization; there is no fixed entry-count limit. Certificates are process-local and reconstructed from applied state after restart or snapshot installation; they do not change durability or permit a hit against a different read fence.

Reactive parents can skip their callback when their only potentially changed derived child returns an equal outcome. Changed dependency edges, errors, cycle validation, and garbage collection still apply. Several potentially changed branches fall back to application evaluation order, so stale branches are not speculatively evaluated.

A mutation either publishes its entire resulting state or none of it. Throws, invalid results, or exhausted budgets discard staged writes. Ordinary query evaluation does not install durable roots. Use materialization for frequently read values whose maintenance cost is justified; leave expensive, infrequently read rankings unmaterialized. Cycles and excessive graph depth fail evaluation. Dynamic dependencies are tracked each time a callback runs.

Definitions and the public method table.

All application traffic goes through the deployed http table. Definition names do not become public routes automatically. A deployment atomically changes code, aliases, schema, maintenance registration, and recomputed materialized state. A rejected deployment leaves the previous application active.

Fresh queries on any replica obtain a quorum-confirmed position and wait for local application. Concurrent queries can share fences and run independently of the writer. Replica-local queries read one coherent locally applied committed snapshot without a per-read fence; state, code, and aliases may lag without a bound, and switching replicas can move backward in revision. This is an explicit application policy, not a client switch. A restarted node whose durable log extends beyond its recovered application checkpoint first requires a quorum-confirmed recovery fence and local replay, including before replica-local reads and watches. After this shared startup barrier clears, replica-local reads again require no per-read quorum.

Incremental aggregates.

import { aggregate, collection } from "@flower-js/sdk";

const lines = collection<{ shop: string; cents: number }>("lines")
  .index("byShop", ["shop"]);
const total = aggregate("shop.total", {
  source: lines, index: "byShop",
  initial: () => 0,
  add: (sum, row) => sum + row.cents,
  remove: (sum, row) => sum - row.cents,
});
// Register collections: [lines], definitions: [total].
// In a mutation: ctx.materialize(total, shop);
// In any callback: ctx.get(total, shop);

Reducers receive no database context. They must be deterministic and order-independent, with remove undoing add. Flower cannot prove that algebra for user code. Use safe integer units for exact totals; floating-point sums can depend on history. Updating a row removes its old contribution and adds its new contribution; moving equality groups updates both accumulators.

The first evaluation scans matching rows. Retained accumulators subsequently process changed rows. Unmaterialized query-only aggregates may rebuild on each query. A reducer error is stored as a derived error; a later relevant change rebuilds rather than reusing a partial accumulator. Redeploying rebuilds retained aggregates. Backfill, initialization, and rebuilds are synchronous and budgeted. Index entries, accumulator state, rows, and dependencies replicate and recover together.

Call methods from outside the database.

import { FlowerClient, FlowerError } from "@flower-js/sdk/client";

const db = new FlowerClient("http://node-1:7101", {
  queryUrls: ["http://node-1:7101", "http://node-2:7101", "http://node-3:7101"],
});
const requestId = crypto.randomUUID(); // Persist before sending.
try {
  await db.mutate("orders.save", { id: "42", cents: 900 }, { requestId });
} catch (error) {
  if (error instanceof FlowerError) console.error(error.status, error.code);
  // After an uncertain response, retry the same body and requestId.
}

A lost response does not prove a mutation failed. Preserve the exact request ID, arguments, and expected revision when retrying an uncertain call. Changing content under the same ID yields REQUEST_ID_REUSED; a stale expected revision yields REVISION_CONFLICT. A full admission queue returns 503. Cancellation stops waiting, not an already committed mutation. Receipts are durable. Without initialized retry retention they remain indefinite; initialized histories use explicit epoch floors and authenticated session acknowledgements. Expired or acknowledged requests cannot execute again, even after result collection; see retry retention.

The SDK does not retry failed entry-node connections automatically. Use any reachable member: servers forward writes and deployments to the current leader while retaining request IDs and expected revisions. If that entry member itself is unavailable, select another reachable endpoint. The benchmark’s discovery and retry loop is harness behavior, not a hidden SDK guarantee. Query endpoint rotation also has no automatic retry when one selected endpoint fails.

Move a tenant; keep its identity.

A named partition is an isolated logical database with its own application bundle, data, derived graph, indexes, timers, lease tokens, revision and retry receipts. Multiple partitions share a physical Raft group. Existing tenant keys in the default database do not automatically become movable partitions: choose this boundary when creating a database. Cross-partition reads and cross-group transaction methods are not supported inside named partitions in this first version.

import { FlowerClient } from "@flower-js/sdk/client";

const cluster = new FlowerClient("http://catalog-1:7101", {
  adminToken: process.env.FLOWER_ADMIN_TOKEN,
});
await cluster.registerGroup({ id: "west", addresses: ["west-1:7101", "west-2:7101", "west-3:7101"] });
await cluster.registerGroup({ id: "east", addresses: ["east-1:7101", "east-2:7101", "east-3:7101"] });
await cluster.createPartition("tenant-a", "west", { requestId: "create-tenant-a" });
await cluster.waitForPartition("tenant-a");
const tenant = cluster.partition("tenant-a");
// Deploy a bundle through tenant.deploy(bundle), then call its exposed methods.
await cluster.resize(["west", "east"], { requestId: "grow-two-groups" });
console.log(await cluster.layout()); // Durable progress; resize continues after this client exits.

Operation and failure tradeoffs

Every participating process sets FLOWER_GROUP, FLOWER_CATALOG_GROUP, and FLOWER_GROUPS, a JSON map from bootstrap group IDs to arrays of host:port peers. The map must include itself and the stable catalog. Keep a configured catalog bootstrap peer reachable through membership changes. Initialize each physical group separately; all peers use compatible protocol versions and the same peer credential; operator calls use the separate operator credential. Registered worker groups can then change without restarting the catalog. The catalog's default namespace stores placement metadata; use named partitions for applications.

The source first captures a durable immutable base and keeps serving reads and writes during copying. The destination imports that base into invisible state. The source then freezes, transfers a final difference including record and receipt deletions, and verifies the complete final image before catalog cutover and destination activation. The source becomes a fenced tombstone; its retained base is released. Every step is idempotent and recoverable. In-flight writes either commit before freeze and travel with their receipts, or fail the epoch/status check. Stale owners cannot acknowledge new writes. In-doubt transactions prevent freeze. A failed transfer after freezing remains paused until its required groups regain quorum; failure during copying leaves the source serving. Losing the client does not cancel a move. Logical-partition transaction methods remain supported; unresolved participants or coordinators delay the freeze, while completion and recovery can still proceed.

Other partitions have separate writer actors and state, but still share CPU, Wasm pools, disk bandwidth and their physical Raft log. Large imports can cause contention. Pause duration grows with image size, network/storage speed and failures; it is not guaranteed to be a few milliseconds. The source persists its captured base until retirement and computes the final difference against frozen state, rather than retaining every intermediate update. If that difference is larger than a full image or exceeds FLOWER_PARTITION_TAIL_MAX_BYTES, transfer falls back to a full frozen image. Optional FLOWER_PARTITION_BASE_MAX_BYTES bounds base admission; both settings are unset by default. Migration export still caches a complete encoded base, difference, or fallback image in memory despite chunked transport. Encoding acquires shared Control capacity before retaining source roots, and the cached image holds its byte reservation until replacement or retirement. Difference construction also reserves workspace; exhausted control budgets can delay a move after freeze. This differs from file-backed Raft snapshots: neither mechanism removes the live in-memory database or guarantees a fixed pause duration.

Active routes share a configurable cache: FLOWER_ROUTE_CACHE_MS defaults to 1,000 ms. Expired entries require a fresh catalog lookup; catalog unavailability then blocks named requests and terminates affected watches. This exchanges some catalog dependence for prompt ownership updates. Replica-local data can still lag within the selected owner; cached ownership may lag within this interval. Native replicated epoch checks protect writes and fresh reads independently of cached routing. On migration, an SSE stream ends with an ownership/unavailable error; reconnect through the stable partition client for a new snapshot. There is no event-log replay or automatic SDK reconnect.

Control calls require the operator token. Application partition URLs are not an authentication boundary: put a trusted gateway in front of public deployments and bind callers to allowed partitions. Default-namespace clients use server-side leader routing; named clients also use server-side group routing. Neither requires SDK leader discovery. Retry uncertain mutations with the exact same request ID and body. Preflight checks transfer and control envelopes. Destination HTTP and evaluator budgets must also suit the application workload; heterogeneous leader budgets or later policy reductions can leave a move pending until capacity is restored. The current pizza capacity report measures static groups, not migration overhead.

One watched value, efficient deltas.

import { FlowerClient } from "@flower-js/sdk/client";

const db = new FlowerClient("http://node-1:7101");
const stop = new AbortController();
for await (const { revision, value } of db.watch("pizza.board", null, { signal: stop.signal })) {
  console.log(revision, value);
  // break or stop.abort() releases the subscription.
}

Watches can be spread across replicas. Fresh watches use the same quorum/read semantics as fresh queries; replica-local watches may lag and can go backward after reconnecting elsewhere. A stream can coalesce intermediate revisions. It is a value subscription, not an event log or exactly-once change feed. A patch is used only when it is worthwhile and fits server allowances; otherwise the server sends a replacement snapshot.

Identical invocations share evaluation, diffing and immutable encoded buffers within a node/logical database, scoped by the full admitted principal, deployment and declared consistency. Every subscriber independently authorizes and obtains its read fence on refresh, including idle ticks; credentials are not shared. The first snapshot may start above zero. Subsequent snapshots must increase sequence and may skip values as a complete reset; patches require consecutive sequence and an exact baseSequence. Deployment or principal-scope changes terminate with WATCH_SCOPE_CHANGED, requiring a new watch.

The SDK validates content type, UTF-8 SSE framing, sequence/baseSequence, revision progression within a stream, JSON pointers, operation counts, and reconstructed-value size. Malformed data becomes WATCH_PROTOCOL_ERROR. Server error events terminate the iterator. Breaking, returning the iterator, or aborting interrupts a pending read and releases transport resources. Consumers must explicitly reconnect and accept a new snapshot after interruption.

Server send buffers and evaluation admission are bounded. Updates send immediately while the one-item output queue has room. When a changed update finds the queue full, the subscriber waits for space and batches intermediate changes into one refresh of the latest value, reacquiring admission, its declared read fence and current authorization before sending. A missed producer update uses a full reset snapshot. Consumers waiting for room to send that update close after the configured send timeout. There is no fixed total watch-count cap. Memory, sockets, evaluation cost, quorum checks, and update frequency determine useful capacity. Exposed reads still need application authorization; one watched value can contain sensitive data from many records.

Expiry is ordinary TypeScript.

Include helper.records in define({collections}) for indexed sweeps. Expiration is enforced when read, even without a sweep. The deadline means now >= expiresAt is expired. Zero-duration policies expire immediately. Physical deletion is a separate policy and consumes transaction work; schedule sweeps at a cadence appropriate to dataset size. Use the scheduler for business actions at a deadline instead of assuming expiry itself triggers a callback.

Lease work, then fence the result.

All mutating helper calls require a MutationContext. Include queue.records in define({collections}) once per backing collection. Claims seek the oldest pending item and inspect expired leases in bounded pages to preserve original creation-order FIFO; cost grows with expired leases, not completed history or valid leases. Sweeps traverse only expired leases. Scopes provide logical separation, not authorization. There is no lease-renewal method.

A mismatched, missing, expired, or replaced lease fails with LEASE_LOST. Tokens increase across these helpers within one logical database, using a reserved counter that helpers never delete. A named partition carries its counter when moved; separate partitions or default databases have independent counters, even when sharing a physical Raft group. A deduplicated claim retry returns its original deadline; that lease may already have expired. Workers must check it before starting work and must enforce fencing at external sinks too. Flower cannot make an arbitrary external side effect exactly once.

Run business logic later.

import { collection, define, mutation } from "@flower-js/sdk";
import { scheduler } from "@flower-js/sdk/scheduler";

const orders = collection<{ state: string }>("orders");
const bake = mutation("internal.bake", (ctx, id: string) => {
  const order = ctx.get(orders, id);
  if (order) ctx.set(orders, id, { ...order, state: "ready" });
  return null;
});
const timers = scheduler("oven", { bake });
const place = mutation("orders.place", (ctx, id: string) => {
  ctx.set(orders, id, { state: "baking" });
  timers.after(ctx, `bake:${id}`, 5_000, "bake", id);
  return { id };
});
export default define({ collections: [timers.records], http: { place }, maintenance: timers.maintenance });

Maintenance seeks the earliest pending deadline through the declared ordered index; explicit scan() remains a complete inspection. Deadlines mean “not before,” not exact scheduling. Queued writes, maintenance cadence, elections, outages, and CPU work can delay execution. On success, the timer’s removal and handler writes commit together; the handler may replace its own timer ID. On failure, all handler writes roll back, then the error handler stores a retry or failed state. Retry delay doubles after each failed attempt up to the configured maximum; exhausted attempts remain inspectable as failed timers.

The default host polls maintenance every 250 ms and permits a 50 ms catch-up burst, checked between invocations. Each continuation evaluates against the preceding staged state with its own revision and rollback boundary; successful continuations can share one durable batch commit. An idle call stops the burst. The error handler sees the failed invocation’s original ctx.now(), while failedAt records completion time for retry delays. These are operator settings, not scheduler promises. Callback code may execute again before a durable commit; place external effects in a worker queue.

Sign the petals. Seal the envelope.

nacl and jwt are synchronous native crypto facades. Import them from @flower-js/sdk/crypto or the SDK root in deployed TypeScript. They require Flower’s QuickJS host; this package does not install a Node/browser crypto polyfill. The server keeps cryptographic work in Rust while typed-array bytes cross the Wasm bridge directly.

NaCl: the complete high-level surface

Raw binary arguments/results are Uint8Array; subarray offsets and lengths are respected. Applicable key arguments also accept the managed handles described below, and managed box.before returns an opaque SharedKey. Functions do not overwrite their input arrays. Detached, shared, out-of-bounds, proxy-wrapped, and differently typed inputs are rejected. There is no lowlevel API. All functions and their attached constant properties are frozen.

NaCl wire layouts and high-level names follow TweetNaCl. Two deliberate compatibility differences strengthen Ed25519 handling: verification rejects weak/malleable legacy cases, and signing rejects secret keys whose public half disagrees with the seed. X25519 retains its all-zero low-order-point behavior. These primitives do not provide peer identity, key rotation, nonce management, or protocol design.

JWT: compact signed and encrypted tokens

Verification/decryption require exp unless requireExpiration: false. A present exp is always checked: nowSeconds - tolerance < exp. A present nbf requires nowSeconds + tolerance >= nbf. Present exp/nbf/iat must be finite NumericDates; iat is type-checked but does not itself impose a maximum age or reject future issuance. Requested issuer, subject and type must match exactly. Present iss/sub must be strings. aud may be one string or an array of strings: at least one configured audience must match; a token audience without an explicit validation audience is rejected.

Time comes from Flower’s sampled invocation clock, never a caller override or ambient OS clock. verify/decrypt register that clock read as a reactive dependency, so query caching cannot indefinitely reuse an earlier expiration decision. Reading a value produced earlier does not itself revoke a session or delete a token; methods must perform the validation required by their own authorization rules.

Protected headers accept only alg, kid and typ, plus enc for JWE. Unsupported/critical header extensions, compression, alternate serialization forms, duplicate JSON members, malformed base64url and algorithm/key mismatches are rejected. There is no JWKS fetching or unrestricted key selection, implicit HMAC conversion of public-key PEM, nested-token policy, or unverified decode helper. Claims and options must be finite JSON objects; custom claims still need application validation.

Before calling the maintained key parser, Flower checks canonical DER framing, at most 128 nested ASN.1 values, and tag/OID components that fit unsigned 64-bit integers. These guards bound native parser stack use and identifier arithmetic against hostile keys; supported standard key identifiers fit. They are key-parser representation and recursion boundaries, not a message-size or workload cap.

Execution, keys and budgets

Native entropy is forbidden during static and per-invocation bundle initialization and in queries/derived callbacks, including derives evaluated within a mutation. Explicit seeds, keys and nonces support pure callbacks. A custom nacl.setPRNG implementation can generate bytes in JavaScript, but its mutable state resets with the callback snapshot; an unsafe deterministic generator can repeat keys or nonces. Prefer the native mutation-only source for fresh randomness. JWT’s automatic nonce source ignores that override.

Binary inputs are borrowed from guest memory without JSON/base64 conversion. Rust output is copied into the guest once and adopted as a Uint8Array. Claims/options/token strings use native string conversion and JSON/JOSE processing where required. HTTP arguments, stored values and ordinary method results remain finite JSON: encode bytes explicitly when crossing those boundaries. A fresh guest is used for every callback. Raw caller-supplied keys are not persistently cached; managed keys reuse native contexts without exposing private bytes to JS. Raw keys embedded in bundles or records become ordinary replicated application state.

Aggregate native input and output bytes are each bounded by FLOWER_RESULT_MAX_BYTES. Native workspace admission additionally uses FLOWER_RUST_MEMORY_BYTES: a conservative 64 × total input bytes for JWT and managed dispatch, or 2 × predicted output for raw NaCl. These estimates are intentionally conservative, not precise RSS accounting. Wasmtime’s configured memory bound applies to guest buffers. The shared evaluation deadline is checked before and after native calls; long native operations cannot be interrupted halfway by Wasm epochs. Exceeded budgets poison the invocation even if JS catches an ordinary crypto exception. Invalid types, lengths, keys and JWT validation failures throw; NaCl authenticated-open/sign-open failures return null and detached verification returns false.

See the short usage example, native implementation, and binary guest ABI.

Keys stay below the petals.

Declare a capability in TypeScript; keep private material and reusable crypto contexts in Rust. A declaration grants nothing until an operator binds it inside the same logical database.

Which operation can use which handle?

Existing byte-key overloads still work. Managed JWT sign/verify infer their trusted algorithm; NaCl lengths, formats, aliases and failure results otherwise remain as documented above. Managed NaCl uses the active version by default and carries no embedded version identifier. Save keyVersion(key).version alongside ciphertext/signatures, then use keyVersion(key, savedVersion) for historical decryption/verification. Native permission checks restrict historical selectors to read operations under the original binding; they cannot sign, encrypt or derive a new shared handle. Managed JWT verification/decryption instead selects an unrevoked immutable version from its authenticated kid, restricted to the explicitly bound key; external tokens without that managed kid need the raw public-key API.

Provision and administer.

Use new FlowerClient(url, {adminToken}); select a named database with client.partition(id). All key methods require operator authorization. Mutating methods accept ControlOptions (requestId?, signal?), automatically generating an ID if absent. Preserve the exact ID and request contents after an uncertain response. Methods return {revision, value, duplicate}; revision is the committed database revision and value is the public catalog, with the cache exception below.

# Install the same protected wrapping file on every authorized server.
umask 077
openssl rand 32 > /secure/flower-wrapping.key
# Start each server with FLOWER_KEYRING_FILE=/secure/flower-wrapping.key.

# SDK CLI: supply FLOWER_URL and FLOWER_ADMIN_TOKEN for your cluster.
flower key generate session-signing --algorithm Ed25519 --request-id create-session-key
flower key bind sessions session-signing --usages sign,verify --request-id bind-sessions
flower deploy sessions.ts --request-id deploy-sessions
flower key rotate session-signing --request-id rotate-sessions-2
flower key list
flower key cache

# Native runtime executable: plaintext stays on this local machine.
/path/to/native/flower key seal --wrapping-key-file /secure/flower-wrapping.key \
  --format pem < private.pem > sealed.json
# SDK CLI sends only the authenticated encrypted envelope.
flower key import imported-signing sealed.json --algorithm Ed25519 \
  --request-id import-signing

Both executables are called flower: the SDK CLI handles network administration; only the native runtime executable implements key seal. The latter reads plaintext from stdin, accepts --format raw|pem|der and requires --wrapping-key-file PATH. It outputs sealed JSON only. SDK key import NAME FILE --algorithm ALGORITHM reads that JSON; FILE - reads encrypted JSON from stdin. No raw-secret command-line option exists. Keep the wrapping file separate from the Raft data directory and backups; losing it loses access to the encrypted keys.

Import formats: HS256 uses raw bytes (at least 32); A256GCM, XSalsa20Poly1305 and X25519 use exactly 32 raw bytes. Ed25519 accepts a 32-byte seed, a validated 64-byte NaCl secret, or PKCS#8 PEM/DER. P256 accepts a valid 32-byte scalar or PKCS#8 PEM/DER. RSA accepts PKCS#8 or PKCS#1 private PEM/DER (2048–8192 bits). Public-only imports, certificates, SEC1 EC wrappers and password-encrypted PEM are unsupported. Normal DER parser guards also apply.

Fresh key/nonce generation uses the host OS CSPRNG, not a seeded consensus RNG. Mutation evaluation runs on the leader and commits resulting changes; no PRNG state is replicated or advanced inside a reusable QuickJS snapshot. Explicit-input HMAC/Ed25519 signing is deterministic, P256 uses RFC 6979, and provider-internal randomness such as RSA blinding remains native. Opaque SharedKey identities can use native randomness even in read callbacks; they are transient control tokens, not persistent random application data. Supplying explicit nonces makes the caller responsible for uniqueness across retries and concurrent calls.

Authorization, rotation and reactive state.

The catalog belongs to a logical database and has a stable random security domain; named partitions isolate their catalogs and preserve identity when moved. A bundle declaration contains no key bytes and grants no access to another database. Managed calls are unavailable during both forms of bundle initialization. Each callback pins one snapshot of declarations and policy; a rotation cannot switch its version halfway through execution.

When any managed keys are declared, Flower upgrades all query/watch evaluations to fresh quorum-backed snapshots, including aliases marked replica-local. This deliberately gives up stale-read availability for current revocation policy. Already acquired snapshots may finish under their admitted policy. Secret-dependent query results bypass result caching; managed key resolution records a reactive catalog dependency. Binding changes, rotation and revocation recompute dependent materialized values in the same atomic update. Writer revision validation prevents committing speculative work against a conflicting policy revision. A revoked/locked dependency is an error, never an obsolete materialized answer.

Key generation/import and envelope encryption happen before log submission. Raft commits encrypted catalog changes, derived results and request receipts; followers apply those changes without rerunning TypeScript or generating keys. Failed or uncertain administrative calls may have computed discarded material; request receipts identify the sole committed result. As with other derived computations, policy changes may cause dependent values to contain an error instead of a formerly valid result.

Retention is separate from Raft log history: compaction/snapshots reclaim old log entries while current records remain mutable. Request receipts retain fingerprints and original results. Uninitialized histories retain them indefinitely; opt-in epochs and session acknowledgements reclaim results while preserving replay fences. Rotation retains encrypted prior key versions, and revocation marks them unusable without deleting their envelopes. Key-version destruction and wrapping-key rewrap are explicit operator actions; neither happens automatically. Snapshots retain this metadata and receipt history.

Revocation affects newly admitted Flower operations; it cannot retract already returned bytes, revoke tokens checked by external systems, erase every in-flight context, or provide end-user authentication. Application methods still decide who may ask them to sign, decrypt or expose public keys. A managed key is non-exportable to the guest, not to an authorized host administrator.

Native reuse and operating limits.

The first resolution of an operation/key/version authorizes it against the callback’s pinned policy and records its dependency. Repeated calls may reuse that authorized native context, while enforcing its pinned permissions; this is not a fresh Raft barrier or catalog parse per crypto function. The node-wide cache is consulted only when callback-local reuse misses, so its hit/miss counters exclude that fast path. Contexts are shared across isolated QuickJS callbacks and reader workers, keyed by domain, immutable key/version, algorithm and authenticated envelope. Ed25519 JWT and strict NaCl verification keep their distinct native verification semantics. No plaintext, nonce, JWT validity decision or claims result is retained in this cache. Retention budgets do not cap all active/in-flight provider allocations or process RSS, and expired entries are removed lazily on access/eviction rather than by a secure-erasure timer.

A node must unlock required material before serving managed work; missing/wrong wrapping keys fail closed. Readiness follows the derived values actually read: a source-only query can still run on a locked node. Reusing a managed materialized value conservatively unlocks/prepares all unrevoked catalog versions, so a cold read can pay more than the cost of its own key. Migration carries encrypted catalog metadata with data/timers/receipts; the destination validates all unrevoked key versions before cutover. Give authorized destination nodes the same wrapping key. Otherwise a move remains staged/paused until configuration is corrected and nodes restarted; it rolls forward after recovery. KMS/HSM providers, cross-wrapping-key migration without rewrapping, private-key export, raw-key persistent context caching, and general exportable secrets are not implemented.

Envelopes authenticate domain, key ID, immutable version, algorithm and purpose. Replicated storage/backups contain only encrypted key material; the protected host still has unwrapped keys in memory. Zeroizing owned buffers does not promise protection from process dumps, swapping or host compromise. Sealed imports protect private material; native TLS protects the full connection. The default h2c mode requires a trusted network or external transport protection. For design and recovery details see managed-key operating contract.

Retain the version with the ciphertext

keyVersion(key, version?) returns a ManagedKeyVersion: frozen public metadata {kind:"keyVersion",key:ManagedKey,version:string}. Omit the version to resolve the current full flower.<keyId>.<version> identifier. Save that identifier beside raw NaCl ciphertext and use the version-qualified key for later decryption. Selectors cannot escape the bound logical key. Historical versions permit verification/decryption/public-key access, not signing/encryption/derivation. JWT headers already carry their kid.

ManagedKeyCatalog version metadata also reports retired, destroyed and wrappingId (null after destruction). The CLI exposes key retire|destroy|rewrap NAME [--version N]; preserve --request-id across uncertain retries. Caches resolve current policy before reuse; cache TTL is not a revocation delay.

Transactions between logical databases.

Validate business rules inside participant methods. Calls in one logical target see earlier staged calls in that target; results preserve original plan order. A successful call receipt contains {results, value?}. Its revision and expectedRevision belong only to the coordinator, not a global sequence.

Two-phase commit durably prepares each participant, then commits an immutable coordinator decision. A prepared lock blocks fresh reads, new watches, writes, deployment, and maintenance throughout its participating logical database, including unrelated keys. Other named partitions on the same physical group remain available; a group target locks that group’s root namespace. Replica-local readers can lag behind the lock and are excluded from atomic visibility guarantees. Existing reads with an acquired snapshot may finish. Separate requests still do not form a global snapshot; related reads must be part of one transaction if they require participant barriers.

Unavailable coordinators can leave participants blocked indefinitely. There is no timeout that silently drops prepared work. TRANSACTION_PREPARED requires recovery/connectivity; TRANSACTION_ABORTED is durable for that request ID. Retry uncertain operations with identical content and the same ID; start a new ID after correcting a durable abort. Operator-driven closure and bounded collection reclaim completed decision and participant detail behind durable rejection floors; receipt retirement is a separate explicit protocol. Incomplete work, unavailable participants, and still-admissible aborted request IDs can block closure. See retry retention and transaction closure. Automatic time-based retirement and arbitrary cross-group point-in-time restore are not implemented.

Configure FLOWER_GROUP, FLOWER_GROUPS, and a shared peer secret on every participant, with separate operator credentials. Internal calls use peer-authenticated pooled HTTP/2 (verified HTTPS with native TLS) and checked compatibility contracts. Plans share existing time, memory, command, and RPC budgets. See the full transaction and recovery protocol. Independent-group benchmark throughput does not measure this coordination workload.

Pool connections with HTTP/2.

import { FlowerClient } from "@flower-js/sdk/client";
import { createHttp2Transport } from "@flower-js/sdk/http2";

const transport = createHttp2Transport();
try {
  const db = new FlowerClient("http://localhost:7101", { fetch: transport.fetch });
  console.log(await db.query("pizza.board"));
} finally {
  await transport.close();
}

The ordinary request deadline covers headers and body; for successful SSE it covers response headers only. AbortSignal or close controls stream lifetime. SSE uses a bounded backpressured stream rather than a lifetime response cap; event and reconstructed-value allowances belong to WatchOptions. Idle timeout closes unused sessions, not active streams.

This adapter performs no HTTP/1 fallback, redirects, automatic retries, or compressed-response decoding. HTTPS uses verified TLS, with no insecure switch or hostname override. Session admission, request/response size, truncation, invalid status, unsupported encoding, and premature stream closure produce Error objects with H2_* codes. HTTP status errors still become FlowerError in the client. A failed connection may leave a mutation’s outcome uncertain.

Build application bundles.

Per-invocation initialization reruns module initialization for each callback. Static initialization runs module code once before snapshotting; choose it only when initialization does not depend on invocation bindings. Before capturing a reusable base or static image, QuickJS collects unreachable cycles and resets its normal 50% allocation headroom. Automatic collection and configured memory/execution limits remain enabled. Method and derived contexts are frozen during trusted sandbox setup, before module initialization; application overrides of Object.freeze do not intercept their construction. Each callback still receives a fresh isolated image; static initialization does not make mutable globals persistent. Deploying validates and recomputes the application under runtime budgets; successful bundling alone is not successful deployment.

Imported packages must be compatible with the isolated runtime and synchronous finite-JSON contract. Bundling a Node dependency does not grant server filesystem or network access. Keep client transport/build helpers in external programs; only application declarations and pure helper code belong in the bundle.

CLI: build, deploy, call, watch.

The SDK installs the flower command. Use npx flower in an npm project or node sdk/cli.ts in a checkout. Commands print JSON; failures print a readable code/status to stderr and exit nonzero. Watch prints one reconstructed result per line and stops on SIGINT/SIGTERM.

JSON_ARGS defaults to null. Prefix a filename with @ to read its JSON contents. Quote shell JSON carefully. CLI watch allowances are positive safe integers and affect only the local parser. The CLI does not discover leaders, retry uncertain writes, reconnect watches, or expose membership changes; use the operator HTTP APIs for those operations.

Authorize every delivery.

define({authorize}) registers a private fresh query as the admission hook. It runs before public method execution, retry receipt replay, query-cache access, and every watch refresh. Return a principal to admit the call or null/throw to deny it. Modules without a hook remain public. Business checks that change state stay inside the mutation.

Credentials are a top-level request field, separate from args and the durable business fingerprint. Refreshed credentials for the same subject/tenant recover the original result using the same request ID. A different owner cannot recover it. Claims may change without changing intent, but the original result remains the original result. Authorization failures return 403 FORBIDDEN. Putting JWT checks only inside a mutation does not reauthorize its receipt replay; use the hook for admission.

Authorization currently requires fresh policy and therefore makes protected replica-local methods quorum-dependent. Each check uses one snapshot; mutation preparation is ordered and revision-fenced. Idle watches recheck policy/time on refresh and close on denial. Already-delivered bytes cannot be revoked. Peer and operator traffic still require a protected network; application authorization does not replace transport security.

Prepare indexes and computations while the garden grows.

Editing local computation code changes nothing on the server until its bundle is built and deployed. Direct deployment recomputes retained materializations in one atomic candidate. Staged deployment prepares durable index and graph pages while existing code and policy keep serving, then explicitly activates the prepared graph; it does not defer rebuilding until public queries. Operators control progress and cleanup, with no automatic activation.

Phases, resume and failure

1. backfill: added index definitions are maintained with active indexes while advance fills bounded source pages. Code-only deployments start in rebuilding.
2. rebuilding: advance evaluates adaptive batches of retained roots and their required dependencies in a hidden generation. Source rows are stored once. Each active mutation runs its method body once; its final source/root changes also drive target derived callbacks. Active and completed target results publish atomically. Public methods and authorization still use the active bundle and graph.
3. ready: root traversal is complete. Ordinary mutations synchronously maintain the prepared graph, including root additions and removals; readiness does not revert to rebuilding after a write, and there is no catch-up queue. Target maintenance continues until activation, cancellation or a fatal target failure.
4. active: explicit activation has switched bundle, indexes, aliases, policy, key declarations and graph pointer together. Clock-independent outcomes are reused; clock/key-dependent work is refreshed within normal budgets.
5. canceled / collected: cancellation preserves the active application and makes the target intent terminal. Repeated bounded collection removes obsolete or canceled-build state while protecting active generations and shared indexes. Collect the completed job before beginning another. After activation, use a new deployment to roll forward.

Status and its index/graph cursors survive leader changes, full restarts, snapshots and logical-partition moves. Save the deployment ID with its original bundle, inspect status after uncertainty, and verify both requestId and bundleHash before resuming. Only advance backfill or rebuilding, activate ready, and collect active or canceled; do not try to reactivate a canceled or already-active job. rebuiltRoots counts roots visited by graph pages, excluding roots added by concurrent writes. Counters are not a completion percentage. Aborting an HTTP request does not roll back a committed page. See the restart-aware lifecycle example.

An explicit page or activation error leaves prior committed progress intact. Correct a budget constraint and retry when appropriate, or cancel and collect before staging corrected code. A fatal target-maintenance error inside a source mutation instead records failed with an error; the active mutation can still commit if its output and failure status fit the normal budgets. A failed graph cannot activate and must be canceled and collected. Ordinary derived exceptions retain their stored-error semantics. While a cross-group transaction is prepared, state-changing deployment controls return TRANSACTION_PREPARED; status remains inspectable.

The latest collected summary remains available, so status does not necessarily become null after cleanup. The live deployment request ID is reserved against other writes. If its retry epoch or session is retired during preparation, activation is rejected while cancellation and collection remain available; terminal retry results still obey normal receipt budgets. See retry retention before retiring a deployment identity.

Independent page scheduling and limits

FLOWER_DEPLOYMENT_PAGE_MS accepts positive integer milliseconds, defaults to 200, and is capped by FLOWER_EVALUATION_TIMEOUT_MS. It is independent of FLOWER_WRITER_BATCH_MS and is not an HTTP request field. For example, set FLOWER_DEPLOYMENT_PAGE_MS=20 alongside FLOWER_WRITER_BATCH_MS=200 before starting each node. Settings are read at startup; restart nodes to apply changes. Lower targets favor more, smaller graph pages and shorter competing write stalls; larger targets favor fewer commits and rebuild throughput. Each page holds the logical writer during preparation/commit while committed snapshots remain readable.

maxBytes independently bounds inspected source/index work or the graph patch for one progress call, subject to exact command and transaction limits. Graph pages adapt from observed time and bytes, growing by at most twice per page. The time target is soft: an unsuccessful multi-root candidate can retry only its first root with the full normal evaluation timeout. A page can therefore consume the target plus one full evaluation, admission and commit time. One indivisible root dependency closure and an initial aggregate-group scan must still fit one evaluation; the retained graph metadata must fit memory. Removals, changed existing derived edges and restored metadata can require whole-graph topology validation. Activation clock/key refresh still obeys normal budgets.

Completed target roots add derived maintenance work; the extra generation consumes storage until collection. Speculative mutation preparation is bypassed during target maintenance, while serial batches and grouped commits remain available. Pure build-progress changes preserve valid query caches. Measure both rebuild duration and foreground write latency on the application workload; the target is not an end-to-end latency guarantee. The operator guide explains the tuning workflow and links historical benchmark results with their original settings and limitations.

Source transformations are application mutations

Neither direct nor staged code deployment automatically rewrites stored source records. Deploy compatibility code that accepts both old and new versions, then run bounded application migration mutations. Store each batch's transformed rows and durable cursor/version in the same mutation so progress cannot move ahead of the data. Use record-version guards for resumed work and retain each batch's request ID after uncertain responses. For all-record conversions, page by source key with ctx.scan(rows, {gt: afterKey, limit: 100}), omitting gt initially. Read the saved key from the migration record inside the mutation and commit its next value with converted rows; record completion when a page is empty. Make ordinary writers emit the new shape before traversal so inserts behind the cursor are safe. For indexed subsets, use a declared index with ctx.range and stable ordering fields; cursors use each call's current snapshot, so moved rows may be skipped or repeated and missing/nonscalar indexed fields are excluded. Avoid unbounded scans and growing offsets.

Keep concurrent writers compatible and verify remaining old versions plus application invariants before activating code that removes compatibility. The active and staged target computations must both understand intermediate rows. Target maintenance runs target derived callbacks against the active mutation's final source/root changes; it does not rerun the target mutation method body. If the migration needs two source representations, the application must write both explicitly. Application migration progress is separate from the deployment's graphCursor. Collection and derived names are durable identities: changing them or TypeScript interfaces does not rename records or roots. Explicitly copy source records and materialize/unmaterialize roots through a compatibility transition. Protect migration methods with application authorization; the operator token protects admin APIs, not public mutation access. Logical-partition movement preserves stored contents and code and is distinct from record-shape conversion. See the migration workflow, range contracts and mutation context.

Bound history without reviving requests.

Retention is opt-in and uses replicated logical epochs. Initialize once, issue scoped IDs, advance the accepted epoch floor, then collect retired receipts in bounded steps. There is no automatic wall-clock expiry: a clock jump must not erase a promised retry window. Epoch retirement is irreversible within one history.

After initialization, unscoped external mutation IDs are rejected. Existing legacy receipts remain retained; new scoped receipts can be collected only below the replicated floor. RETRY_WINDOW_EXPIRED means the outcome is no longer available through this protocol, not that the mutation failed. HISTORY_MISMATCH rejects another history. RECEIPT_BUDGET_EXCEEDED rejects new work instead of evicting promised results. Initialization and epoch changes wait for distributed transactions to complete; receipt GC does not delete their decisions or participant fences.

Normal Raft recovery preserves identity. Disaster restore needs external fencing and a new history; merely restoring an older floor or key catalog is unsafe. Physical database files and backups may retain reclaimed data. See the retention protocol and restore tradeoffs.

Distributed transaction closure

Closure never releases an undecided prepared transaction on timeout. Committed client receipts remain governed by their retry contract. An aborted coordinator record can close only after the original request ID is provably inadmissible; legacy aborts can block a prefix until retention is initialized and rejects unscoped IDs. Participant floors survive deletion, snapshots, restart and movement. This protocol does not make independently restored old participants safe.

Operational limits are part of the API.

Each logical database has an ordered writer; readers run independently, and named partitions have separate preparation lanes while sharing their physical group’s ordered Raft log. Durable acknowledgements wait for quorum commitment and application. Adaptive group commit reduces storage overhead but trades queue latency against throughput. Independent candidates can prepare in parallel; their dependencies are validated in order, and conflicting candidates rerun before commitment. A 503 queue rejection is backpressure, not extra capacity.

For every environment variable and cross-budget rule, use the complete operator settings reference. The operating walkthrough, membership and rolling-upgrade procedure, HTTP/storage protocol, and latest measured report provide the next level of detail. Failure recovery is tested; deployments still need validation against their own workloads and failure scenarios.