foldkit-sync 0.5.1 → 0.5.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.
Files changed (2) hide show
  1. package/README.md +25 -28
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -88,36 +88,17 @@ new visible state = replay(A, B, C, X, D, E)
88
88
  The local edit never needed to wait for that exchange to appear. Reconciliation
89
89
  changes the base underneath it and replays the still-pending operations on top.
90
90
 
91
- The full lifecycle of one durable Message is:
91
+ The lifecycle is:
92
92
 
93
93
  ```text
94
- user dispatches durable Message
95
- |
96
- v
97
- replay through application update immediately
98
- |
99
- v
100
- persist operation in local outbox
101
- |
102
- v
103
- optimistic state is visible now
104
- |
105
- network later
106
- v
107
- server assigns authoritative order
108
- |
109
- v
110
- replica adopts committed operations / checkpoint
111
- |
112
- v
113
- drop acknowledged or rejected pending operations
114
- |
115
- v
116
- replay remaining pending operations on the new base
117
- ```
118
-
119
- That is the core of `foldkit-sync`. Transport, browser mounting, presence, and
120
- LWW fields are layers around this mechanism.
94
+ local durable Message → optimistic update + local persistence
95
+ → exchange → authoritative commit or refusal
96
+ → new base + replay of remaining pending operations
97
+ ```
98
+
99
+ These are separate milestones. Showing an optimistic value is not an
100
+ acknowledgment from either local storage or the server. Watch persistence and
101
+ replica status when deciding what the UI may call saved.
121
102
 
122
103
  ## Install
123
104
 
@@ -219,6 +200,18 @@ replay function, operation codecs, and server journal contract from the same
219
200
  application declaration. There is no parallel sync-specific version of
220
201
  `update` to keep aligned.
221
202
 
203
+ ### Declaration is not a running replica
204
+
205
+ The example above defines codecs and replay rules. It has not opened storage,
206
+ created an outbox, connected to a server, or mounted a view. For the application
207
+ path, continue with [mounting](#mounting-the-full-foldkit-application). Use
208
+ [the replica API](#running-a-replica) when you need to control that lifecycle.
209
+
210
+ `SelectedTodo` stays local because it is outside the durable MessageSet.
211
+ Adding a Message to that set is a semantic decision: its update must be safe
212
+ to replay and confined to the shared projection. An intent that starts a
213
+ Command should instead produce a deterministic fact, as described next.
214
+
222
215
  ## Wiring: the contract joins an assembly
223
216
 
224
217
  The contract joins a `foldkit-bundle` assembly contract-only, so the Module
@@ -619,6 +612,10 @@ server rejects. The agent learns nothing about cursors or operations.
619
612
  `mounted.committed` is a source (`{ get, subscribe }`), not a Projection: it reads
620
613
  the replica, not the Model, and tells subscribers after every exchange.
621
614
 
615
+ Remote draws the same line over its own cache, with the same words and a
616
+ different mechanism: see [what a reader sees while a change is in
617
+ flight](../../docs/state-model.md#what-a-reader-sees-while-a-change-is-in-flight).
618
+
622
619
  ## Fragments: compose one document from features
623
620
 
624
621
  Large applications do not need one giant Sync declaration. Declare feature
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-sync",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
4
4
  "description": "A local-first replica of a shared Foldkit projection: offline outbox, optimistic updates, and reconciliation.",
5
5
  "keywords": [
6
6
  "foldkit",
@@ -38,7 +38,7 @@
38
38
  "LICENSE"
39
39
  ],
40
40
  "dependencies": {
41
- "foldkit-surface": "0.3.0"
41
+ "foldkit-surface": "0.4.0"
42
42
  },
43
43
  "peerDependencies": {
44
44
  "effect": "^4.0.0-rc.112",
@@ -50,7 +50,7 @@
50
50
  "jsdom": "26.1.0",
51
51
  "tsdown": "^0.23.0",
52
52
  "typescript": "5.9.3",
53
- "foldkit-agent": "0.3.1"
53
+ "foldkit-agent": "0.3.2"
54
54
  },
55
55
  "scripts": {
56
56
  "build": "tsdown",