@datafn/server 0.1.0 → 0.1.3

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
@@ -779,3 +807,23 @@ export {
779
807
  ## License
780
808
 
781
809
  MIT
810
+
811
+ ## Repairing inherited inactivity
812
+
813
+ `recomputeAncestorInactive` scans a bounded batch in one namespace; resume with
814
+ `nextCursor`. `recomputeAncestorInactiveAll` repeats scans until a verification
815
+ sweep finds no changes or skipped compare-and-set writes. Check `converged`;
816
+ `updated: 0` alone is not proof of completion. `skipped` counts concurrent-write
817
+ conflicts. Dry runs count mismatches without writing.
818
+
819
+ Repair derives values from ancestor archive/trash state and relation links,
820
+ never from stored `isAncestorInactive` flags. Cycles, missing/malformed parents,
821
+ and traversal-limit violations throw explicit errors. `batchSize`, `maxSweeps`
822
+ and `maxGraphNodes` must be positive safe integers; `maxGraphNodes` defaults to
823
+ 10,000 visited nodes per repaired row. A failed batch can be replayed safely;
824
+ earlier completed writes are idempotent.
825
+
826
+ Run repair with ancestor/link mutations quiesced. The compare-and-set protects
827
+ each derived field from a concurrent propagation write; it does not provide an
828
+ atomic snapshot across all ancestor records. Resume and verify after concurrent
829
+ activity settles before relying on repaired values for a consumer migration.