foldkit-sync 0.5.2 → 0.5.4

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 +24 -31
  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
 
@@ -190,7 +171,7 @@ const TodoSync = Sync.forApplication(App).make({
190
171
  // This slice of Model is replicated.
191
172
  // The writable Projection lets Sync install checkpoints/reconciled state back
192
173
  // into the application Model without owning a second copy of the schema.
193
- shared: Projection.pick(App.fields.todos),
174
+ shared: Projection.pick(App.model.todos),
194
175
 
195
176
  // Only these existing Messages become durable operations.
196
177
  durable: MessageSet.make(App, [
@@ -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
@@ -632,7 +625,7 @@ fragments and compose them into one document:
632
625
  const AppSync = Sync.forApplication(App)
633
626
 
634
627
  const Todos = AppSync.fragment({
635
- shared: Projection.pick(App.fields.todos),
628
+ shared: Projection.pick(App.model.todos),
636
629
  durable: MessageSet.make(App, [
637
630
  Message.CreatedTodo,
638
631
  Message.RenamedTodo,
@@ -640,7 +633,7 @@ const Todos = AppSync.fragment({
640
633
  })
641
634
 
642
635
  const Members = AppSync.fragment({
643
- shared: Projection.pick(App.fields.members),
636
+ shared: Projection.pick(App.model.members),
644
637
  durable: MessageSet.make(App, [Message.Invited]),
645
638
  })
646
639
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-sync",
3
- "version": "0.5.2",
3
+ "version": "0.5.4",
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.1"
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.3"
54
54
  },
55
55
  "scripts": {
56
56
  "build": "tsdown",