@collective-intelligence/extensions-sdk-frontend 0.2.6 → 0.2.8

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.
@@ -0,0 +1,294 @@
1
+ # State machines
2
+
3
+ How next-effect-app models UI flows as XState machines with Effect actors, keeps server data in the QueryCache, resends uncertain writes safely, and checks hard flows with Models.
4
+
5
+ In `next-effect-app`, a UI flow that carries business logic is an XState machine in the `headless/` folder of its package, at `headless/<flow>-machine.ts`. Flows that belong only to the web app live at `apps/web/src/{features,entities}/<domain>/<flow>-machine.ts`. The machine decides where the flow is: editing, reviewing, submitting, failed. Every side effect is an Effect program that the machine runs as an actor, and TanStack Query owns the remote data that those programs read and write.
6
+
7
+ The machine context holds flow state only and never an API response. Two views that show the same record therefore read one cache entry, and no machine keeps a copy that can go stale. Server Components never run machines or Effects; they await a Promise boundary, and machines exist only in client code.
8
+
9
+ ## Machine, task or hook
10
+
11
+ Most of the template does not use a hand-written machine. Pick the smallest tool that covers the flow:
12
+
13
+ | Pick | When | Template examples |
14
+ | -------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
15
+ | XState machine | The flow has steps the user moves through, a lifecycle, or error branches that go back to an earlier step. | Lead intake (edit, review, submit), the CI session (initialize, sign in, refresh, sign out) |
16
+ | `effectTask` | One button runs one Effect and shows one result. | Convert lead, attach a file, sign out |
17
+ | Plain hook | The SDK hooks already cover it, or nothing writes. | `useEntityList`, `useEntityRecord`, `useEntityUpdate`, `useLeadRealtime`, the Lead score card |
18
+
19
+ Plain navigation and synchronous state changes need no actor at all.
20
+
21
+ ## Side effects are Effect actors
22
+
23
+ Each side effect is a `fromEffect(program)` actor from `@collective-intelligence/external-apps-client-sdk-react/effect`, declared in `setup({ actors })`. The actor runs on the `runtime` that the machine gets as input, and a view gets that runtime with `useEffectRuntime()` from the `EffectRuntimeProvider` in `composition/providers`. The intake submit actor calls the app API and then invalidates the intake list, so every view that shows the list refetches:
24
+
25
+ ```ts
26
+ export const submitIntakeActor = (submit: SubmitIntake) =>
27
+ fromEffect(({ draft }: IntakeInput & Readonly<{ draft: IntakeDraft }>) =>
28
+ submit(draft).pipe(
29
+ Effect.tap(() =>
30
+ QueryCache.use((cache) =>
31
+ cache.invalidate(intakeRequestsQuery.queryKey)
32
+ )
33
+ )
34
+ )
35
+ )
36
+ ```
37
+
38
+ Remote data moves only through the `QueryCache` service of the runtime, with `fetch`, `invalidate`, `setData`, `update` and `remove`. Three lint rules enforce this. `ci-solution/effect-actors` requires `fromEffect` actors, and `ci-solution/effect-writes` forbids TanStack `useMutation` everywhere, including hooks and helpers. `ci-solution/no-run-in-view` forbids `fetch` and running an Effect in a view module.
39
+
40
+ ## A machine in the template
41
+
42
+ The intake machine has four steps and a terminal state:
43
+
44
+ - `editing` goes to `reviewing` on `intake.review`.
45
+ - `reviewing` goes back to `editing` on `intake.edit`, or to `submitting` on `intake.confirm`.
46
+ - `submitting` goes to `done` when the actor succeeds, or back to `reviewing` with an error message when it fails.
47
+ - `done` goes to `editing` on `intake.reset`.
48
+
49
+ The `submitting` state invokes the actor. Its `onError` receives the typed failure, so the machine branches on it with `Schema.is`. `IntakeDuplicate` keeps its `_tag` from the server `HttpApi` to the browser, which is why `isDuplicate` works on the client:
50
+
51
+ ```ts
52
+ submitting: {
53
+ invoke: {
54
+ input: ({ context }) => ({ draft: context.draft, runtime: context.runtime }),
55
+ onDone: {
56
+ actions: { params: ({ event }) => event.output, type: "submitted" },
57
+ target: "done",
58
+ },
59
+ onError: {
60
+ actions: assign({
61
+ error: ({ event }) =>
62
+ isDuplicate(event.error)
63
+ ? "This email already has an open intake request."
64
+ : "The request could not be sent. Try again.",
65
+ }),
66
+ target: "reviewing",
67
+ },
68
+ src: "submitIntake",
69
+ },
70
+ },
71
+ ```
72
+
73
+ Leaving the invoking state interrupts the Effect fiber. The machine has no UI of its own: `submitted` is a typed action, and the view provides the toast with `machine.provide({ actions })`. The view runs `useMachine(intakeMachine.provide(...), { input: { runtime } })` and renders by `snapshot.matches("editing")`, `matches("submitting")` and `matches("done")`.
74
+
75
+ The same `provide` call swaps the data source for a demo without a backend. A simulated source lives in `headless/simulated-*.ts`, built with `simulate("<pace>", effect)` from `@acme/app-api`, and only Composition or a test selects it. Tests use the same mechanism. A test drives the machine on a `ManagedRuntime` of the SDK `makeTestQueryCache` layer, never a hand-made `QueryCache` double, and asserts on cache entries or recorded calls:
76
+
77
+ ```ts
78
+ const cache = makeTestQueryCache({ seed: [[intakeRequestsQuery.queryKey, []]] })
79
+ const runtime = ManagedRuntime.make(cache.layer)
80
+ const actor = createActor(
81
+ intakeMachine.provide({
82
+ actors: { submitIntake: submitIntakeActor(submit) }
83
+ }),
84
+ { input: { runtime } }
85
+ ).start()
86
+ // ...
87
+ expect(cache.calls).toEqual([
88
+ { member: "invalidate", queryKey: intakeRequestsQuery.queryKey }
89
+ ])
90
+ ```
91
+
92
+ Under `bun test` the simulated pace is instant.
93
+
94
+ ## Single actions with effectTask
95
+
96
+ For a single action, the SDK `effectTask(run)` wraps one Effect in a small machine with fixed states:
97
+
98
+ - `idle` goes to `running` on `RUN` with an input.
99
+ - `running` goes to `done` on success, with the result in `context.output`, or to `failed` on failure, with the error in `context.error`.
100
+ - `running` goes to `failed` on `CANCEL`, with a `Cause.Interrupt` reason as the error.
101
+ - `done` and `failed` go to `idle` on `RESET`, or back to `running` on `RUN`.
102
+
103
+ A `RUN` or `RESET` that arrives while the task is running is ignored. The convert-lead button is an `effectTask`. Its Effect starts the workflow through the BFF, follows the run to its end, and then marks every CI entity read stale:
104
+
105
+ ```ts
106
+ export const convertLead =
107
+ (start: StartConvert) =>
108
+ ({ followRun, leadId }: ConvertLeadRequest) =>
109
+ Effect.tryPromise({
110
+ catch: () => new ConvertLeadFailed({ step: "start" }),
111
+ try: async () => await start(leadId)
112
+ }).pipe(
113
+ Effect.flatMap(({ runId }) =>
114
+ Effect.tryPromise({
115
+ catch: () => new ConvertLeadFailed({ step: "follow" }),
116
+ try: async () => {
117
+ await followRun(runId)
118
+ }
119
+ })
120
+ ),
121
+ Effect.andThen(
122
+ QueryCache.use((cache) => cache.invalidate(entityReadsKey))
123
+ )
124
+ )
125
+
126
+ export const convertLeadTask = effectTask(convertLead(startConvertLive))
127
+ ```
128
+
129
+ The failure records which step failed, and `convertFailureMessage(snapshot)` maps it to a message for the view. The view calls `useMachine(convertLeadTask, { input: { runtime: useEffectRuntime() } })`, sends `{ type: "RUN", input: { followRun, leadId } }` from the button, and disables the button while `state.matches("running")`. On the server, the BFF route checks `convertLeadRequirement` on every call and starts the run with a fixed idempotency key per Lead:
130
+
131
+ ```ts
132
+ idempotencyKey: ({ leadId }) => `convert-lead:${leadId}`,
133
+ ```
134
+
135
+ ## Uncertain writes and idempotency keys
136
+
137
+ A write is uncertain when the request left the browser and no answer came back. CI may or may not have applied it, and only a resend of the same action settles the question. The Lead attachment flow shows how the template handles this. `attachLeadFile` is an `effectTask` whose Effect checks the file's size and type locally, asks CI for an upload slot, PUTs the bytes straight to storage (never through the BFF), writes `{ attachment: { upload } }` at the Lead's revision with an idempotency key, and then invalidates the entity reads.
138
+
139
+ ```mermaid
140
+ stateDiagram-v2
141
+ [*] --> idle
142
+ idle --> running: RUN with a new file
143
+ state running {
144
+ [*] --> checkFile
145
+ checkFile: Check size and type locally
146
+ askSlot: Ask CI for an upload slot
147
+ putBytes: PUT bytes to storage
148
+ writeLead: Write the Lead with an idempotency key
149
+ invalidateReads: Invalidate entity reads
150
+ checkFile --> askSlot
151
+ askSlot --> putBytes
152
+ putBytes --> writeLead
153
+ writeLead --> invalidateReads
154
+ }
155
+ running --> done: CI confirms the write
156
+ running --> failed: too large, wrong type, storage, conflict, refused
157
+ running --> failed: no answer, reason uncertain, write kept
158
+ failed --> running: Resubmit with the kept write, same key
159
+ failed --> running: RUN with a new file
160
+ done --> running: RUN with a new file
161
+ ```
162
+
163
+ The steps inside `running` are steps of the Effect program, and the machine itself sees one `running` state. A resubmit skips the upload and sends only the final write. The size and type checks use `leadAttachmentAccepts` and `leadAttachmentMaxBytes` (5 MiB) from `@acme/lead/domain`. The CI schema declares the same values on the File field, so CI refuses a larger upload too, while a file that fails the local check sends nothing.
164
+
165
+ The write that might need a resend is a value the failure carries:
166
+
167
+ ```ts
168
+ export const PendingAttachment = Schema.Struct({
169
+ expectedRevision: Schema.String,
170
+ idempotencyKey: Schema.String,
171
+ upload: Schema.String
172
+ })
173
+ ```
174
+
175
+ When the write ends with a rejected promise or an SDK `uncertain` outcome, the task fails with reason `uncertain` and keeps that `PendingAttachment`. Sent again with the same idempotency key, CI applies the write at most once and returns its first answer. `pendingAttachment(snapshot)` reads the kept write from a failed task, and the `LeadAttachment` view shows a "Resubmit attachment" button only when it is not null. The button sends `RUN` with `{ pending }` in place of a new file, which reuses the same key and uploads nothing again. Every failure reason maps to one message, and the uncertain one reads "No answer came from CI, so the file may be attached. Resubmit to finish."
176
+
177
+ > **Warning:** A retry after an uncertain write must resend the same action with the same
178
+ > idempotency key. A new key makes it a new action, and CI could apply the
179
+ > change twice.
180
+
181
+ The SDK entity hooks follow the same rule. Their writes report `conflict`, `rejected` and `uncertain` in `status`; `submit` creates a new action with one operation key, and `resubmit` sends the previous action exactly as it was. Queries and mutations never retry by themselves. While a write is uncertain, `EntityForm` shows every field read-only, so Resubmit sends the draft that the form shows. [SDKs](../develop/sdks.md) lists these hooks.
182
+
183
+ ## Realtime refreshes the cache
184
+
185
+ Realtime reaches the views through the cache. It never sends events into a machine. `useLeadRealtime` subscribes to the Lead topic, and each batch of changes refreshes the SDK entity reads and marks the app API read of each changed id stale:
186
+
187
+ ```ts
188
+ export const leadsTopic: RealtimeTopic = { schema: leadSchemaFqn }
189
+
190
+ export const useLeadRealtime = () => {
191
+ const queryClient = useQueryClient()
192
+ const refreshEntityReads = useEntityChanges(leadContract)
193
+ useRealtimeTopic(leadsTopic, (changes) => {
194
+ refreshEntityReads(changes)
195
+ void refreshLeadReads(queryClient, changes)
196
+ })
197
+ }
198
+ ```
199
+
200
+ Changes carry ids only, and the reads reload. Every write in the template ends the same way, with the cache:
201
+
202
+ | Writer | What it refreshes |
203
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
204
+ | Intake actor | invalidates the intake list query |
205
+ | Convert and attach actors | invalidate `entityReadsKey` |
206
+ | SDK entity hooks | store the confirmed record and reload lists |
207
+ | A write the BFF confirms | expires the Next cache tags of the record |
208
+ | A write outside the BFF (workflow, Studio, agent, another app) | reaches the Realtime Revalidate Route, which expires the Next cache tags |
209
+
210
+ Invalidation is enough for almost every flow, but one case can go wrong. A Realtime change can arrive while this tab's optimistic write is still pending, and a naive refetch would then show the old server value and hide the user's edit. The SDK entity read prevents this by waiting for the writes of its key to settle (`writesSettled`) before it fetches. The template checks that interleaving with a Model.
211
+
212
+ ## Models
213
+
214
+ A Model is a `*.proof.ts` TypeScript module that states the state, actions and invariants of one flow. `tsprover` compiles it to TLA+, and the `tla-ts` checker visits every reachable state. When a rule breaks, the checker prints a trace: the sequence of actions, with the state after each one. An XState machine describes what one user sees step by step in one tab, while a Model describes what can happen when several writers interleave, and the template uses each for its own question.
215
+
216
+ | Construct | Meaning |
217
+ | ---------------------------------------- | ------------------------------------------------------ |
218
+ | top-level `let` | a state variable |
219
+ | exported function that changes state | an action |
220
+ | exported function that returns a boolean | an invariant |
221
+ | guard `if (<condition>) return;` | a precondition |
222
+ | `/** @fair */` | this action must eventually run |
223
+ | `/** @leadsTo target */` | a liveness property |
224
+ | `/** @constraint */` | a bound, so the search ends |
225
+ | `ghost` prefix on a `let` | records what a consumer saw, only to state a guarantee |
226
+
227
+ The Lead Realtime Model in `packages/entities/lead` is trimmed here. The full file also has `writeConfirm`, `otherWrite`, `realtimeChange` and `neverBehindConfirmed`:
228
+
229
+ ```ts
230
+ let server: Revision = 0
231
+ let cached: Revision = 0
232
+ let writePending = false
233
+ let refetchDue = false
234
+ let ghostConfirmed: Revision = 0
235
+ let ghostPredicted: Revision = 0
236
+
237
+ export const writeStart = () => {
238
+ if (writePending) return
239
+ if (server === 2) return
240
+ writePending = true
241
+ ghostPredicted = server === 0 ? 1 : 2
242
+ cached = ghostPredicted
243
+ }
244
+
245
+ /** @fair */
246
+ export const refetch = () => {
247
+ if (!refetchDue) return
248
+ if (writePending) return
249
+ cached = server
250
+ refetchDue = false
251
+ }
252
+
253
+ export const pendingWriteShown = () =>
254
+ !writePending || cached === ghostPredicted
255
+
256
+ /** @leadsTo isFresh */
257
+ export const isRefetchDue = () => refetchDue && !isFresh()
258
+ ```
259
+
260
+ The checker visits 22 states and proves two things. A Realtime refetch never hides the tab's pending optimistic write (`pendingWriteShown`, `neverBehindConfirmed`), and after a Realtime change the views eventually reach the stored revision (`@leadsTo isFresh`). The package runs it with one script:
261
+
262
+ ```bash
263
+ cd packages/entities/lead
264
+ bun run check:models
265
+ ```
266
+
267
+ With no file arguments, `tsprover` checks every `*.proof.ts` below the package and exits with code 1 on any failure. Run it when you change the Lead cache, a Lead write or Lead Realtime.
268
+
269
+ > **Note:** Pin `tsprover` exactly, as the template does with `"tsprover": "0.0.2"`. It
270
+ > and its checker are 0.0.x releases, so any release can change the Model
271
+ > language or the checker.
272
+
273
+ ### When a flow deserves a Model
274
+
275
+ Most demo flows need no Model. Add a `*.proof.ts` only when the flow has one of these:
276
+
277
+ - two or more writers on shared state
278
+ - a background job or retry that touches client-written state
279
+ - recovery or resync
280
+ - a delivery guarantee such as "eventually delivered"
281
+
282
+ In the template, only the optimistic write against a Realtime refetch met that bar. Write one Model per service: the state the service owns becomes a top-level `let`, and each dependency stays outside and enters only as an action. The SDKs ship their own Models for the optimistic write coordinator, the session, the Realtime machine, change-log resync and topic grant tokens, so a demo inherits those guarantees and models only its own flows.
283
+
284
+ ### Sensitivity Proofs
285
+
286
+ A Model that passes may simply never reach the dangerous case. A Sensitivity Proof shows that it does. You break the Model on purpose with one named Mutant, by removing one guard for an invariant or removing `@fair` from one action for a `@leadsTo` property. The checker must report a violation on the Mutant and pass again after you revert it. If the Mutant passes with the same state count, the guarded case is unreachable, and you widen the bounds or add an actor before you prove again.
287
+
288
+ A worked example: a client save and a background hash job both write `hashed`. Without the guard `if (job !== content) return;`, the invariant `hashMatchesContent` fails on the trace `save -> save -> hashJob`, because a stale job writes the hash of old content. With the guard, 11 distinct states pass. Both guards of the Lead Realtime Model have Sensitivity Proofs.
289
+
290
+ ## Related pages
291
+
292
+ - [The solution template](index.md)
293
+ - [SDKs](../develop/sdks.md)
294
+ - [External applications](../develop/external-apps.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/extensions-sdk-frontend",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "description": "Framework-neutral frontend declaration, catalog, and activation contracts for Collective Intelligence extension packages.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -44,7 +44,7 @@
44
44
  "access": "public"
45
45
  },
46
46
  "dependencies": {
47
- "@collective-intelligence/extensions-sdk": "0.2.6"
47
+ "@collective-intelligence/extensions-sdk": "0.2.8"
48
48
  },
49
49
  "peerDependencies": {
50
50
  "effect": "^4.1.0"
@@ -54,7 +54,7 @@
54
54
  "@oxlint/plugins": "1.90.0",
55
55
  "@typescript-eslint/utils": "8.22.0",
56
56
  "bun-types": "^1.4.2",
57
- "effect": "4.1.0",
57
+ "effect": "4.1.2",
58
58
  "eslint": "9.39.5",
59
59
  "eslint-plugin-react-you-might-not-need-an-effect": "latest",
60
60
  "oxfmt": "0.66.0",
@@ -62,5 +62,5 @@
62
62
  "typescript": "7.0.2",
63
63
  "ultracite": "7.10.7"
64
64
  },
65
- "gitHead": "4b3fc24d8d1da8d087ffaacaaec3ca4118d9f8c4"
65
+ "gitHead": "b9fb8e902754f2b7fa4ba97a4103cbb37d7f36f6"
66
66
  }