@datafn/server 0.1.4-maint.0 → 0.2.1

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.
package/README.md CHANGED
@@ -37,6 +37,34 @@ permission-directory projection. See
37
37
  for configuration, error, WebSocket, consistency, migration, and operations
38
38
  contracts.
39
39
 
40
+ ### Initial region placement
41
+
42
+ DataFn provides reusable region selection without embedding a product's data
43
+ residency or capacity policy:
44
+
45
+ ```typescript
46
+ import {
47
+ readDatafnCloudflarePlacementLocation,
48
+ selectDatafnPlacementRegion,
49
+ } from "@datafn/server/placement";
50
+
51
+ const decision = selectDatafnPlacementRegion({
52
+ candidates: regions,
53
+ location: readDatafnCloudflarePlacementLocation(request),
54
+ constraints: [
55
+ (region) => allowedRegionIds.includes(region.regionId),
56
+ (region) => healthyRegionIds.has(region.regionId),
57
+ ],
58
+ });
59
+ ```
60
+
61
+ An eligible explicit preference wins first, trusted coordinates or continent
62
+ metadata rank the remaining regions by distance, and an optional `stableKey`
63
+ enables deterministic fallback. The returned decision records which source was
64
+ used. Applications remain responsible for defining eligible regions, collecting
65
+ explicit organization choices, and atomically claiming the resulting namespace
66
+ through the placement directory.
67
+
40
68
  ---
41
69
 
42
70
  ## Quick Start
@@ -407,6 +435,8 @@ The mutation is rejected with `CONFLICT` if the guard condition is not met.
407
435
 
408
436
  Atomic multi-step transactions mixing queries and mutations.
409
437
 
438
+ Atomic execution needs database transactions. When the adapter reports `capabilities.transactions.supported === false` (for example the Drizzle adapter on SQLite or Cloudflare D1), an atomic transact with any mutation step returns HTTP 400 with `DFQL_UNSUPPORTED` (`details.path: "atomic"`) before anything is written. Send `"atomic": false` to apply steps one at a time.
439
+
410
440
  **Request:**
411
441
 
412
442
  ```json
@@ -779,3 +809,23 @@ export {
779
809
  ## License
780
810
 
781
811
  MIT
812
+
813
+ ## Repairing inherited inactivity
814
+
815
+ `recomputeAncestorInactive` scans a bounded batch in one namespace; resume with
816
+ `nextCursor`. `recomputeAncestorInactiveAll` repeats scans until a verification
817
+ sweep finds no changes or skipped compare-and-set writes. Check `converged`;
818
+ `updated: 0` alone is not proof of completion. `skipped` counts concurrent-write
819
+ conflicts. Dry runs count mismatches without writing.
820
+
821
+ Repair derives values from ancestor archive/trash state and relation links,
822
+ never from stored `isAncestorInactive` flags. Cycles, missing/malformed parents,
823
+ and traversal-limit violations throw explicit errors. `batchSize`, `maxSweeps`
824
+ and `maxGraphNodes` must be positive safe integers; `maxGraphNodes` defaults to
825
+ 10,000 visited nodes per repaired row. A failed batch can be replayed safely;
826
+ earlier completed writes are idempotent.
827
+
828
+ Run repair with ancestor/link mutations quiesced. The compare-and-set protects
829
+ each derived field from a concurrent propagation write; it does not provide an
830
+ atomic snapshot across all ancestor records. Resume and verify after concurrent
831
+ activity settles before relying on repaired values for a consumer migration.