@feltdb/core 0.12.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/dist/build-identity.json +13 -4
  2. package/dist/cli/commands.js +96 -45
  3. package/dist/cli/workspace-integration.js +8 -0
  4. package/dist/collection.d.ts +41 -4
  5. package/dist/collection.d.ts.map +1 -1
  6. package/dist/collection.js +116 -47
  7. package/dist/composition.d.ts.map +1 -1
  8. package/dist/composition.js +11 -1
  9. package/dist/create/build-identity.json +13 -4
  10. package/dist/create/cli.js +49 -40
  11. package/dist/create/create.js +32 -19
  12. package/dist/create/package-versions.js +1 -1
  13. package/dist/create/server-source/Cargo.lock +18 -3
  14. package/dist/create/server-source/Cargo.toml +4 -2
  15. package/dist/create/server-source/crates/feltdb/Cargo.toml +20 -0
  16. package/dist/create/server-source/crates/feltdb/LICENSE +21 -0
  17. package/dist/create/server-source/crates/feltdb/README.md +75 -0
  18. package/dist/create/server-source/crates/feltdb/src/agent_state.rs +320 -0
  19. package/dist/create/server-source/crates/feltdb/src/agent_transition_contract.rs +1545 -0
  20. package/dist/create/server-source/crates/feltdb/src/authority.rs +145 -15
  21. package/dist/create/server-source/crates/feltdb/src/lib.rs +227 -23
  22. package/dist/create/server-source/crates/feltdb/src/state_model.rs +1 -5
  23. package/dist/create/server-source/crates/feltdb/src/worker_mesh.rs +204 -1
  24. package/dist/create/server-source/crates/feltdb/src/workload.rs +685 -53
  25. package/dist/create/server-source/crates/feltdb/tests/agent_state_native.rs +1188 -0
  26. package/dist/create/server-source/crates/feltdb/tests/agent_transition_contract_conformance.rs +2884 -0
  27. package/dist/create/server-source/crates/feltdb/tests/authority_transaction_identity.rs +534 -0
  28. package/dist/create/server-source/crates/feltdb/tests/fixtures/agent_transition_corpus.json +23340 -0
  29. package/dist/create/server-source/crates/feltdb/tests/production_readiness_contract.rs +18 -12
  30. package/dist/create/server-source/crates/feltdb/tests/workload_envelope_contract.rs +17 -5
  31. package/dist/create/server-source/crates/feltdb-client/Cargo.toml +29 -0
  32. package/dist/create/server-source/crates/feltdb-client/LICENSE +21 -0
  33. package/dist/create/server-source/crates/feltdb-client/README.md +70 -0
  34. package/dist/create/server-source/crates/feltdb-client/src/application.rs +527 -0
  35. package/dist/create/server-source/crates/feltdb-client/src/authority.rs +679 -0
  36. package/dist/create/server-source/crates/feltdb-client/src/control.rs +292 -0
  37. package/dist/create/server-source/crates/feltdb-client/src/error.rs +227 -0
  38. package/dist/create/server-source/crates/feltdb-client/src/events.rs +146 -0
  39. package/dist/create/server-source/crates/feltdb-client/src/lib.rs +466 -0
  40. package/dist/create/server-source/crates/feltdb-client/tests/fixtures/README.md +4 -0
  41. package/dist/create/server-source/crates/feltdb-client/tests/fixtures/private-ca.pem +20 -0
  42. package/dist/create/server-source/crates/feltdb-client/tests/fixtures/server-key.pem +28 -0
  43. package/dist/create/server-source/crates/feltdb-client/tests/fixtures/server.pem +20 -0
  44. package/dist/create/server-source/crates/feltdb-client/tests/private_ca.rs +95 -0
  45. package/dist/create/server-source/crates/feltdb-server/Cargo.toml +20 -1
  46. package/dist/create/server-source/crates/feltdb-server/LICENSE +21 -0
  47. package/dist/create/server-source/crates/feltdb-server/README.md +12 -1
  48. package/dist/create/server-source/crates/feltdb-server/src/agent_execution.rs +511 -0
  49. package/dist/create/server-source/crates/feltdb-server/src/auth.rs +28 -0
  50. package/dist/create/server-source/crates/feltdb-server/src/backup.rs +6 -2
  51. package/dist/create/server-source/crates/feltdb-server/src/lib.rs +21 -0
  52. package/dist/create/server-source/crates/feltdb-server/src/main.rs +845 -138
  53. package/dist/create/server-source/crates/feltdb-server/tests/rust_client.rs +683 -0
  54. package/dist/create/server-source/crates/feltdb-wasm/Cargo.toml +3 -1
  55. package/dist/create/setup-summary.js +40 -0
  56. package/dist/create/template/default-project/README.md +12 -7
  57. package/dist/create/template/default-project/src/pages/Dashboard.tsx +1 -1
  58. package/dist/create/template/dot-feltdb-README.md +3 -3
  59. package/dist/db.d.ts +27 -1
  60. package/dist/db.d.ts.map +1 -1
  61. package/dist/db.js +60 -21
  62. package/dist/development-runtime-bridge.d.ts +20 -0
  63. package/dist/development-runtime-bridge.d.ts.map +1 -1
  64. package/dist/development-runtime-bridge.js +74 -4
  65. package/dist/embedded-transaction.d.ts +75 -8
  66. package/dist/embedded-transaction.d.ts.map +1 -1
  67. package/dist/embedded-transaction.js +124 -18
  68. package/dist/error-codes.d.ts +2 -0
  69. package/dist/error-codes.d.ts.map +1 -1
  70. package/dist/error-codes.js +2 -0
  71. package/dist/feltdb.d.ts +1 -11
  72. package/dist/feltdb.d.ts.map +1 -1
  73. package/dist/file-db.d.ts +6 -0
  74. package/dist/file-db.d.ts.map +1 -1
  75. package/dist/file-db.js +43 -11
  76. package/dist/http-db.d.ts +13 -0
  77. package/dist/http-db.d.ts.map +1 -1
  78. package/dist/http-db.js +33 -4
  79. package/dist/indexeddb-db.d.ts.map +1 -1
  80. package/dist/indexeddb-db.js +65 -41
  81. package/dist/memory-db.d.ts.map +1 -1
  82. package/dist/memory-db.js +29 -8
  83. package/dist/studio/{KeyManagementPanel-DZuSeWBK.js → KeyManagementPanel-skUNnKRw.js} +36 -28
  84. package/dist/studio/app.d.ts +8 -1
  85. package/dist/studio/app.d.ts.map +1 -1
  86. package/dist/studio/components/KeyManagementPanel.d.ts.map +1 -1
  87. package/dist/studio/components/KeyManagementPanel.js +1 -1
  88. package/dist/studio/components/RouteErrorBoundary.d.ts +5 -0
  89. package/dist/studio/components/RouteErrorBoundary.d.ts.map +1 -0
  90. package/dist/studio/components/index.js +2 -2
  91. package/dist/studio/{components-Bivm2lX6.js → components-BSGmHfif.js} +6 -6
  92. package/dist/studio/control-plane/Agents.d.ts.map +1 -1
  93. package/dist/studio/control-plane/Data.d.ts.map +1 -1
  94. package/dist/studio/control-plane/Instance.d.ts +4 -1
  95. package/dist/studio/control-plane/Instance.d.ts.map +1 -1
  96. package/dist/studio/control-plane/Operations.d.ts +4 -1
  97. package/dist/studio/control-plane/Operations.d.ts.map +1 -1
  98. package/dist/studio/control-plane/Overview.d.ts.map +1 -1
  99. package/dist/studio/control-plane/Schema.d.ts.map +1 -1
  100. package/dist/studio/control-plane/context.d.ts +4 -1
  101. package/dist/studio/control-plane/context.d.ts.map +1 -1
  102. package/dist/studio/control-plane/index.js +2 -2
  103. package/dist/studio/control-plane/primitives.d.ts +24 -0
  104. package/dist/studio/control-plane/primitives.d.ts.map +1 -1
  105. package/dist/studio/{control-plane-CLm69XwX.js → control-plane-CaBA7Rgv.js} +1374 -1298
  106. package/dist/studio/index.d.ts +1 -0
  107. package/dist/studio/index.d.ts.map +1 -1
  108. package/dist/studio/index.js +415 -237
  109. package/dist/studio/navigation.d.ts +57 -0
  110. package/dist/studio/navigation.d.ts.map +1 -0
  111. package/dist/studio/studio.css +1 -1
  112. package/dist/studio/utils/control-plane-api.d.ts +2 -0
  113. package/dist/studio/utils/control-plane-api.d.ts.map +1 -1
  114. package/dist/studio/utils/control-plane-api.js +9 -4
  115. package/dist/studio/utils/service-api.d.ts.map +1 -1
  116. package/dist/studio/utils/service-api.js +5 -4
  117. package/dist/studio-app/assets/{feltdb_wasm-DACcD-zs.js → feltdb_wasm-3hDngl1h.js} +1 -1
  118. package/dist/studio-app/assets/feltdb_wasm_bg-CFQT4gCy.wasm +0 -0
  119. package/dist/studio-app/assets/index-Dql1hS5m.js +30 -0
  120. package/dist/studio-app/assets/{index-CiC8VY-a.css → index-vi21oEQa.css} +1 -1
  121. package/dist/studio-app/index.html +2 -2
  122. package/dist/telemetry.d.ts +1 -0
  123. package/dist/telemetry.d.ts.map +1 -1
  124. package/dist/telemetry.js +4 -3
  125. package/dist/transaction-identity.d.ts +62 -0
  126. package/dist/transaction-identity.d.ts.map +1 -0
  127. package/dist/transaction-identity.js +138 -0
  128. package/dist/transaction.d.ts +50 -5
  129. package/dist/transaction.d.ts.map +1 -1
  130. package/dist/transaction.js +28 -0
  131. package/dist/wasm/feltdb_wasm_bg.wasm +0 -0
  132. package/dist/wasm/package.json +1 -1
  133. package/dist/workspace/local-development-authority.d.ts +19 -0
  134. package/dist/workspace/local-development-authority.d.ts.map +1 -1
  135. package/dist/workspace/local-development-authority.js +335 -15
  136. package/package.json +1 -1
  137. package/dist/create/server-source/crates/feltdb-wasm/test.db +0 -0
  138. package/dist/studio-app/assets/feltdb_wasm_bg-BejThWID.wasm +0 -0
  139. package/dist/studio-app/assets/index-CoZaxnlm.js +0 -30
@@ -1,5 +1,5 @@
1
1
  import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
2
- import { AtomicTransactionError, conditionalRefusal } from './transaction.js';
2
+ import { AtomicTransactionError, TransactionIdConflictError, conditionalRefusal } from './transaction.js';
3
3
  import { FELTDB_INTENT_COLLECTION, FELTDB_INTENT_EVENT_COLLECTION } from './intent.js';
4
4
  import { FELTDB_PROPOSAL_EVENT_COLLECTION, PROPOSAL_TRANSITIONS } from './proposal.js';
5
5
  import { FELTDB_COMPOSITION_COLLECTION, FELTDB_COMPOSITION_CONTRACT_COLLECTION, FELTDB_COMPOSITION_TOPOLOGY_COLLECTION, FELTDB_COMPOSITION_VERSION_COLLECTION, FELTDB_STATE_ATTRIBUTION_COLLECTION, FELTDB_STATE_CHANGE_COLLECTION, FELTDB_STATE_DEPENDENCY_COLLECTION, FELTDB_STATE_IMPACT_COLLECTION, FELTDB_STATE_OBSERVATION_COLLECTION, FELTDB_STATE_OWNERSHIP_COLLECTION, FELTDB_STATE_PROPOSAL_COLLECTION, canonicalDigest, changedFields, computeImpactSurface, consumerUri, emptyImpactReads, impactReadSet, impactSurfaceDigest, parseStateUri, recordValue, recordVersion, redactImpactSurface, stateUri, } from './state-impact.js';
@@ -1181,6 +1181,16 @@ export class CompositionConsumer {
1181
1181
  });
1182
1182
  }
1183
1183
  catch (error) {
1184
+ // `apply_<proposal id>` names the application of one proposal. If the
1185
+ // authority already holds that id with different contents, another
1186
+ // attempt applied this proposal first and its recorded facts -- when it
1187
+ // was applied, under which decisions -- are its own. This call applied
1188
+ // nothing, and is not a stale read of state, so no refusal is recorded
1189
+ // against the proposal.
1190
+ if (error instanceof TransactionIdConflictError) {
1191
+ throw fail(`State proposal ${proposalId} was already applied by another attempt (transaction ${transactionId} is committed with different contents). `
1192
+ + 'Nothing was applied by this call.', FeltDBErrorCode.CONFLICT);
1193
+ }
1184
1194
  const refusal = conditionalRefusal(error);
1185
1195
  const lostRace = refusal.conflict
1186
1196
  || (error instanceof AtomicTransactionError && /conflict|PRECONDITION_FAILED/i.test(`${error.name} ${error.code ?? ''}`))
@@ -1,8 +1,13 @@
1
1
  {
2
- "schema": "feltdb.core-build-identity.v1",
2
+ "schema": "feltdb.build-identity.v2",
3
3
  "package": "create-feltdb",
4
- "version": "0.12.1",
5
- "source_digest": "sha256:95a6ebf48be2a6be56fad60c24a10b62d93878857e728448913d9bc243e8ce3a",
4
+ "version": "0.13.0",
5
+ "git": {
6
+ "sha1": "b67312f73ea647ffea6f87337303c170d40d541d",
7
+ "dirty": false
8
+ },
9
+ "path_in_vcs": "tools/create-feltdb",
10
+ "source_digest": "sha256:7435af3423598673fcce76eb77444ee1e160f39f3fd83a0a788517e315bd3444",
6
11
  "inputs": [
7
12
  "Cargo.lock",
8
13
  "Cargo.toml",
@@ -15,5 +20,9 @@
15
20
  "tools/cli",
16
21
  "tools/create-feltdb"
17
22
  ],
18
- "files": 731
23
+ "files": 776,
24
+ "build": {
25
+ "command": "npm run build",
26
+ "node": "v24.9.0"
27
+ }
19
28
  }
@@ -11,15 +11,18 @@ import { spawn, spawnSync } from 'child_process';
11
11
  import { createProject } from './create.js';
12
12
  import { FELTDB_PACKAGE_VERSION } from './package-versions.js';
13
13
  import { configureManagedAccount, finalizeManagedProvisioning } from './managed-account.js';
14
+ import { RUNTIME_CHOICES, agentsIncluded, describeSetup } from './setup-summary.js';
14
15
  import { localFeltdbExecutable } from './development-handoff.js';
15
16
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
16
17
  function parseArgs(args) {
17
18
  const options = {
18
19
  runtime: 'browser',
19
20
  framework: 'react',
20
- distributed: true,
21
+ // Distribution and the browser AI builder add services and downloads a
22
+ // first project does not need; each is one flag away.
23
+ distributed: false,
21
24
  agents: true,
22
- webllm: true,
25
+ webllm: false,
23
26
  capabilities: 'search',
24
27
  };
25
28
  for (let i = 0; i < args.length; i++) {
@@ -42,6 +45,9 @@ function parseArgs(args) {
42
45
  case '--framework':
43
46
  options.framework = args[++i];
44
47
  break;
48
+ case '--distributed':
49
+ options.distributed = true;
50
+ break;
45
51
  case '--no-distributed':
46
52
  options.distributed = false;
47
53
  break;
@@ -164,29 +170,28 @@ async function promptForOptions(defaults) {
164
170
  { label: 'Yes', value: true },
165
171
  { label: 'No', value: false },
166
172
  ];
167
- return {
168
- runtime: await select('Where should FeltDB run?', [
169
- { label: 'Browser', value: 'browser', description: 'local-first with durable browser storage' },
170
- { label: 'Node.js', value: 'node', description: 'application server or worker' },
171
- { label: 'Self-hosted', value: 'self-hosted', description: 'dedicated FeltDB server' },
172
- { label: 'Managed', value: 'managed', description: 'FeltDB-hosted persistence, sync, and workloads' },
173
- ], defaults.runtime),
174
- framework: await select('Choose an application framework:', [
175
- { label: 'React', value: 'react' },
176
- { label: 'Vanilla TypeScript', value: 'vanilla' },
177
- ], defaults.framework),
178
- distributed: await select('Enable distributed operation?', yesNo, defaults.distributed),
179
- agents: await select('Include an autonomous agent example?', yesNo, defaults.agents),
180
- webllm: await select('Install WebLLM for private natural-language app building?', [
181
- { label: 'Yes', value: true, description: 'build FeltDB schemas, capabilities, workflows, and UI locally with AI' },
182
- { label: 'No', value: false, description: 'skip the browser model and AI builder' },
183
- ], defaults.webllm),
184
- capabilities: await select('Choose starter capabilities:', [
173
+ const runtime = await select('Where does your application\'s data live?', RUNTIME_CHOICES.map(choice => ({ label: choice.label, value: choice.value, description: choice.summary })), defaults.runtime);
174
+ const framework = await select('Choose an application framework:', [
175
+ { label: 'React', value: 'react', description: 'a complete starter: sign-up, projects, invitations, activity, assistants' },
176
+ { label: 'Vanilla TypeScript', value: 'vanilla', description: 'a minimal page over the same database' },
177
+ ], defaults.framework);
178
+ // The React starter's assistants are part of its tour and need no model, so
179
+ // only the vanilla template asks; its capabilities are chosen here too.
180
+ const agents = framework === 'react' ? true
181
+ : await select('Include an agent example?', yesNo, defaults.agents);
182
+ const capabilities = framework === 'react' ? defaults.capabilities
183
+ : await select('Choose starter capabilities:', [
185
184
  { label: 'Search', value: 'search' },
186
185
  { label: 'Vector search', value: 'vector' },
187
186
  { label: 'Search + vector search', value: 'search,vector' },
188
- ], defaults.capabilities),
189
- };
187
+ ], defaults.capabilities);
188
+ const webllm = await select('Add the private AI app builder (WebLLM)?', [
189
+ { label: 'No', value: false, description: 'add it later with npm install @feltdb/webllm' },
190
+ { label: 'Yes', value: true, description: 'builds schemas and UI with a model that runs in your browser: a download of a few hundred MB on first use, and WebGPU' },
191
+ ], defaults.webllm);
192
+ // Distribution is a deployment decision, not a first-run one: `--distributed`
193
+ // records it, and development always runs one local authority.
194
+ return { runtime, framework, distributed: defaults.distributed, agents, webllm, capabilities };
190
195
  }
191
196
  async function main() {
192
197
  const args = process.argv.slice(2);
@@ -211,9 +216,9 @@ Deployment Target (Explicit):
211
216
  Best for: Client-side apps, offline-first experiences
212
217
  No server required, full offline capability
213
218
 
214
- --server Node.js server runtime with server-side FeltDB authority
215
- Best for: Server-side applications, API servers
216
- Requires production FeltDB instance or self-host
219
+ --server Data lives in a FeltDB authority the application connects to
220
+ Best for: shared state, server-side work, a path to self-hosting
221
+ \`feltdb dev\` runs a local authority; deploy to feltdb-server
217
222
 
218
223
  --self-host Dedicated FeltDB server with Docker Compose
219
224
  Best for: Staging first, then explicit production promotion
@@ -230,11 +235,15 @@ Options:
230
235
  --managed Explicit: Managed FeltDB service
231
236
  --runtime <runtime> Alternative: Set runtime (browser, node, self-hosted, managed)
232
237
  --framework <framework> Choose framework: react or vanilla (default: react)
233
- --no-distributed Disable distributed operation
234
- --no-agents Exclude agent examples
235
- --webllm Include the private natural-language FeltDB app builder (default)
236
- --no-webllm Do not install WebLLM or generate the AI builder
237
- --capabilities <list> Choose capabilities: search, vector, or search,vector
238
+ --distributed Record that the application will be deployed to several
239
+ feltdb-server nodes (development always runs one)
240
+ --no-distributed Do not record distributed deployment (default)
241
+ --no-agents Exclude the agent example (vanilla template; the React
242
+ starter always includes its assistants)
243
+ --webllm Include the private natural-language app builder; downloads
244
+ a model into the browser on first use and needs WebGPU
245
+ --no-webllm Do not install WebLLM (default)
246
+ --capabilities <list> Vanilla template capabilities: search, vector, or search,vector
238
247
  --no-install Skip npm install
239
248
  --no-start Skip automatic feltdb dev startup
240
249
  -y, --yes Use all defaults (non-interactive mode)
@@ -294,13 +303,13 @@ Learn more: https://github.com/rkendel1/feltdb`);
294
303
  console.log('\n═══════════════════════════════════════════════');
295
304
  console.log('📦 DEPLOYMENT TARGET');
296
305
  console.log('═══════════════════════════════════════════════');
297
- console.log(`\nRuntime: ${options.runtime.toUpperCase()}`);
298
- console.log(`Description: ${runtimeDescriptions[options.runtime]}`);
299
- console.log(`Framework: ${options.framework}`);
300
- console.log(`Distributed: ${options.distributed ? 'yes' : 'no'}`);
301
- console.log(`Agents: ${options.agents ? 'yes' : 'no'}`);
302
- console.log(`WebLLM: ${options.webllm ? 'yes — natural-language app builder' : 'no'}`);
303
- console.log(`Capabilities: ${options.capabilities}`);
306
+ if (options.framework === 'react' && !options.agents) {
307
+ console.log('\nNote: the React starter always includes its assistants; --no-agents applies to the vanilla template.');
308
+ }
309
+ options.agents = agentsIncluded(options);
310
+ console.log('');
311
+ for (const line of describeSetup(options))
312
+ console.log(line);
304
313
  console.log('\n═══════════════════════════════════════════════\n');
305
314
  const projectDir = path.resolve(process.cwd(), projectName);
306
315
  let projectCreated = false;
@@ -362,13 +371,13 @@ Learn more: https://github.com/rkendel1/feltdb`);
362
371
  }
363
372
  }
364
373
  else {
365
- console.log('Project is ready. Start the application with:');
374
+ console.log('Project is ready. Start it with:');
366
375
  console.log(` cd ${projectName}`);
367
376
  if (!shouldInstall)
368
377
  console.log(' npm install');
369
- console.log(' npm run dev');
370
- console.log('Start FeltDB development tooling separately with:');
371
378
  console.log(' npm run feltdb:dev');
379
+ console.log('This starts the application, the development authority, and Studio together.');
380
+ console.log('Do not also run npm run dev: that second copy is not managed by FeltDB.');
372
381
  }
373
382
  }
374
383
  catch (error) {
@@ -196,6 +196,25 @@ ${hasAgents ? ` agent WorkspaceAssistant {
196
196
  tsconfig.compilerOptions.types = ['vite/client'];
197
197
  }
198
198
  fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
199
+ // Browsers do not expose VITE_* through process.env, so the database must be handed its
200
+ // namespace explicitly; otherwise it opens the shared `default` store and `feltdb dev` cannot
201
+ // recognise the application. A managed (remote) runtime resolves its target from its URL.
202
+ //
203
+ // The generated application runs in the browser whatever the deployment target. For a
204
+ // browser target its state is the browser's own (IndexedDB). For a Node.js or self-hosted
205
+ // target the state lives in a FeltDB authority, so the browser application connects to it:
206
+ // the URL the developer configured, else the authority `feltdb dev` started. Opening a
207
+ // browser store there instead would leave the application writing data Studio and the
208
+ // authority never see.
209
+ const namespaceExpression = `import.meta.env.VITE_FELTDB_NAMESPACE || ${JSON.stringify(applicationName)}`;
210
+ const createDatabaseCall = runtime === 'managed'
211
+ ? 'createFeltDB()'
212
+ : runtime === 'browser'
213
+ ? `createFeltDB({ namespace: ${namespaceExpression} })`
214
+ : `createFeltDB({
215
+ namespace: ${namespaceExpression},
216
+ server: { url: import.meta.env.VITE_FELTDB_URL || import.meta.env.VITE_FELTDB_AUTHORITY_URL || 'http://127.0.0.1:7700' },
217
+ })`;
199
218
  // Create main application files
200
219
  const feltdbTs = `import { configureDevelopmentRuntimeBridge, createFeltDB } from '@feltdb/core';
201
220
 
@@ -209,7 +228,7 @@ configureDevelopmentRuntimeBridge({
209
228
  applicationUrl: import.meta.env.VITE_FELTDB_APPLICATION_URL,
210
229
  });
211
230
 
212
- export const db = createFeltDB();
231
+ export const db = ${createDatabaseCall};
213
232
 
214
233
  // Collections
215
234
  export const projects = db.collection('Project');
@@ -1193,7 +1212,7 @@ root.render(
1193
1212
  }
1194
1213
  fs.writeFileSync(path.join(projectDir, 'feltdb.flow'), fs.readFileSync(path.join(canonicalTemplate, 'feltdb.flow'), 'utf8').replace('app FeltDBStarter', `app ${appName}`));
1195
1214
  const databasePath = path.join(srcDir, 'feltdb.ts');
1196
- fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = createFeltDB();`));
1215
+ fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = ${createDatabaseCall};`));
1197
1216
  }
1198
1217
  }
1199
1218
  else {
@@ -1216,6 +1235,8 @@ main().catch(console.error);
1216
1235
  <head>
1217
1236
  <meta charset="UTF-8">
1218
1237
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
1238
+ <!-- An inline icon: without one the browser requests /favicon.ico and logs a 404. -->
1239
+ <link rel="icon" href="data:,">
1219
1240
  <title>${applicationName}</title>
1220
1241
  </head>
1221
1242
  <body>
@@ -1558,22 +1579,17 @@ A FeltDB Workspace application demonstrating local-first database capabilities.
1558
1579
 
1559
1580
  ## Quick Start
1560
1581
 
1561
- Start the application:
1582
+ Start everything:
1562
1583
 
1563
1584
  \`\`\`bash
1564
1585
  npm install
1565
- npm run dev
1566
- \`\`\`
1567
-
1568
- The application will be available at http://localhost:5173 (or your configured port).
1569
-
1570
- In a second terminal, start FeltDB authority, pairing, and Studio and attach it
1571
- to the application explicitly:
1572
-
1573
- \`\`\`bash
1574
1586
  npm run feltdb:dev
1575
1587
  \`\`\`
1576
1588
 
1589
+ \`feltdb dev\` starts the application, the development authority, pairing, and Studio together
1590
+ and prints the address of each. Do not also run \`npm run dev\`: that second copy is not
1591
+ managed by FeltDB, so Studio cannot see it.
1592
+
1577
1593
  ## FeltDB Workspace Showcase
1578
1594
 
1579
1595
  This application demonstrates core FeltDB capabilities:
@@ -1698,17 +1714,14 @@ Never expose \`FELTDB_MANAGED_CONTROL_API_KEY\` or \`FELTDB_TOKEN\` through a \`
1698
1714
 
1699
1715
  ## Development
1700
1716
 
1701
- ### Start Development Server
1702
- \`\`\`bash
1703
- npm run dev
1704
- \`\`\`
1705
-
1706
- ### Start FeltDB Development Tooling
1707
-
1717
+ ### Start the Development Environment
1708
1718
  \`\`\`bash
1709
1719
  npm run feltdb:dev
1710
1720
  \`\`\`
1711
1721
 
1722
+ This runs the application (\`npm run dev\` under FeltDB's management), the development authority,
1723
+ and Studio. Running \`npm run dev\` yourself starts an unmanaged second copy.
1724
+
1712
1725
  ### Build for Production
1713
1726
  \`\`\`bash
1714
1727
  npm run build
@@ -1,4 +1,4 @@
1
1
  // One release train keeps generated applications installable. The repository
2
2
  // validation script checks these values against every workspace manifest.
3
- export const FELTDB_PACKAGE_VERSION = '0.12.1';
3
+ export const FELTDB_PACKAGE_VERSION = '0.13.0';
4
4
  export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;
@@ -494,13 +494,14 @@ checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
494
494
 
495
495
  [[package]]
496
496
  name = "feltdb"
497
- version = "0.2.0"
497
+ version = "0.2.2"
498
498
  dependencies = [
499
499
  "async-stream",
500
500
  "async-trait",
501
501
  "bincode",
502
502
  "criterion",
503
503
  "ed25519-dalek",
504
+ "feltdb",
504
505
  "rand 0.8.7",
505
506
  "serde",
506
507
  "serde_json",
@@ -510,15 +511,29 @@ dependencies = [
510
511
  "wasmi",
511
512
  ]
512
513
 
514
+ [[package]]
515
+ name = "feltdb-client"
516
+ version = "0.2.2"
517
+ dependencies = [
518
+ "feltdb",
519
+ "reqwest",
520
+ "serde",
521
+ "serde_json",
522
+ "tokio",
523
+ "tokio-rustls",
524
+ "uuid",
525
+ ]
526
+
513
527
  [[package]]
514
528
  name = "feltdb-server"
515
- version = "0.2.0"
529
+ version = "0.2.2"
516
530
  dependencies = [
517
531
  "argon2",
518
532
  "async-stream",
519
533
  "axum",
520
534
  "base64",
521
535
  "feltdb",
536
+ "feltdb-client",
522
537
  "futures-core",
523
538
  "hmac",
524
539
  "password-hash",
@@ -537,7 +552,7 @@ dependencies = [
537
552
 
538
553
  [[package]]
539
554
  name = "feltdb-wasm"
540
- version = "0.2.0"
555
+ version = "0.2.2"
541
556
  dependencies = [
542
557
  "feltdb",
543
558
  "getrandom 0.2.17",
@@ -1,16 +1,18 @@
1
1
  [workspace]
2
- members = ["crates/feltdb", "crates/feltdb-server", "crates/feltdb-wasm"]
2
+ members = ["crates/feltdb", "crates/feltdb-client", "crates/feltdb-server", "crates/feltdb-wasm"]
3
3
  # The deterministic contracts' WASM implementations are their own
4
4
  # dependency-free workspaces: they are only ever built for
5
5
  # wasm32-unknown-unknown, and a second implementation that inherited this
6
6
  # workspace's dependencies would stop being an independent one.
7
7
  exclude = [
8
+ "crates/feltdb-public-api-check",
8
9
  "crates/feltdb-trigger-contract-wasm",
9
10
  "crates/feltdb-state-diff-contract-wasm",
10
11
  "crates/feltdb-state-conflict-contract-wasm",
12
+ "crates/feltdb-agent-transition-contract-wasm",
11
13
  ]
12
14
  resolver = "2"
13
15
 
14
16
  [workspace.package]
15
- version = "0.2.0"
17
+ version = "0.2.2"
16
18
  edition = "2021"
@@ -2,6 +2,23 @@
2
2
  name = "feltdb"
3
3
  version.workspace = true
4
4
  edition.workspace = true
5
+ # The oldest toolchain CI builds and tests this workspace with (.github/workflows/ci.yml).
6
+ rust-version = "1.96"
7
+ description = "Embedded durable state store: an append-only log with atomic multi-record transactions, version-conditional writes, and idempotent retries"
8
+ license = "MIT"
9
+ repository = "https://github.com/rkendel1/flow_db"
10
+ readme = "README.md"
11
+ keywords = ["database", "embedded", "transactions", "durable", "idempotency"]
12
+ categories = ["database-implementations", "data-structures"]
13
+ # The integration tests and benches read repository files by path (docs, sibling crates) and
14
+ # cannot run from a packaged copy, so they stay in the repository.
15
+ exclude = ["tests/", "benches/", "target/"]
16
+
17
+ [features]
18
+ default = []
19
+ # Implementation, fault-injection and diagnostic modules. Not part of the supported API: no
20
+ # compatibility promise covers anything this exposes. The workspace's own crates enable it.
21
+ unstable-internals = []
5
22
 
6
23
  [dependencies]
7
24
  serde = { version = "1", features = ["derive"] }
@@ -18,6 +35,9 @@ bincode = "1"
18
35
  tokio = { version = "1", features = ["net", "io-util", "rt-multi-thread"] }
19
36
 
20
37
  [dev-dependencies]
38
+ # The integration tests and benches exercise internals, so they build the crate with them. Packages
39
+ # that want only the supported API depend on `feltdb` without the feature.
40
+ feltdb = { path = ".", features = ["unstable-internals"] }
21
41
  criterion = { version = "0.5", features = ["html_reports"] }
22
42
  sha2 = "0.10"
23
43
  tempfile = "3"
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FeltDB Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,75 @@
1
+ # feltdb
2
+
3
+ An embedded, durable state store for Rust. Records live in an append-only log on local disk. Several
4
+ records can change in one atomic transaction, a write can be conditional on the version you read, and a
5
+ transaction can carry an identity so that a retry after an uncertain outcome is recognized instead of
6
+ applied twice.
7
+
8
+ ```toml
9
+ [dependencies]
10
+ feltdb = "0.2"
11
+ serde_json = "1"
12
+ ```
13
+
14
+ ```rust
15
+ use feltdb::{FeltDb, FlowError};
16
+ use serde_json::json;
17
+
18
+ fn main() -> Result<(), Box<dyn std::error::Error>> {
19
+ let db = FeltDb::open("app.db")?;
20
+
21
+ // Create only if absent. A second create is refused in a way you can branch on.
22
+ db.insert_if_absent("orders:o-1", json!({ "status": "pending" }))?;
23
+ assert!(matches!(
24
+ db.insert_if_absent("orders:o-1", json!({})),
25
+ Err(FlowError::PreconditionFailed(_))
26
+ ));
27
+ Ok(())
28
+ }
29
+ ```
30
+
31
+ The crate documentation on docs.rs has a longer, tested example covering atomic transactions and safe
32
+ retries.
33
+
34
+ ## What you can rely on
35
+
36
+ - Acknowledged writes and committed transaction ids survive closing and reopening the database, and a
37
+ process kill.
38
+ - An interrupted, unacknowledged append is discarded on open and reported; its retry is treated as a
39
+ first use.
40
+ - A transaction id names one payload. Reusing an id with a different payload hash fails with
41
+ `FlowError::TransactionIdPayloadMismatch` and writes nothing.
42
+
43
+ ## What is not promised
44
+
45
+ - **Power-loss durability is unproven.** A flush hands bytes to the operating system; it does not force
46
+ them to stable storage. What survives a power cut depends on the filesystem, mount options and the
47
+ drive. See the repository's
48
+ [crash durability](https://github.com/rkendel1/flow_db/blob/main/docs/architecture/crash-durability.md)
49
+ note.
50
+ - **Only the supported API is covered by semver.** While the version is `0.x`, a breaking change to a
51
+ supported item is a minor-version bump. Everything behind the `unstable-internals` feature (fault
52
+ injection, diagnostics, implementation modules) carries no promise at all; do not enable it in
53
+ application code. The supported surface is listed in
54
+ [the Rust API contract](https://github.com/rkendel1/flow_db/blob/main/docs/reference/feltdb-rust-api.md).
55
+ - Plain `insert`, `update` and `delete` are unconditional: `insert` replaces, `update` of a missing key
56
+ creates it, `delete` of a missing key succeeds. Use `insert_if_absent` or `compare_and_set_json` when
57
+ you need a guard.
58
+
59
+ ## Targets
60
+
61
+ Built and tested on native targets. `wasm32-wasip1` compiles. `wasm32-unknown-unknown` compiles only if
62
+ your crate enables `getrandom`'s `js` feature.
63
+
64
+ ## Binaries
65
+
66
+ The package also builds `feltdb-authority`, `feltdb-authority-client` and `feltdb_node`, the process
67
+ authority and its client. `cargo install feltdb` installs them. Most applications want only the library.
68
+
69
+ ## Minimum Rust version
70
+
71
+ 1.96, the oldest toolchain the project's CI builds and tests with.
72
+
73
+ ## License
74
+
75
+ MIT. See [LICENSE](LICENSE).