@gadicc/loom 1.27.0 → 1.28.0

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,403 @@
1
+ # Offline data and media
2
+
3
+ Read the browser-data section whenever retiring a synchronization engine, even
4
+ if the replacement is online-only. Read access leases and download publication
5
+ only when offline use is required. For upload-only apps, continue with
6
+ [legacy delivery and new uploads](#preserve-legacy-delivery-validate-new-uploads-separately)
7
+ and its provider/storage guidance without adopting the download architecture.
8
+
9
+ ## Browser data is an independent migration
10
+
11
+ A server dump cannot contain unsent browser work. Inventory Gongo collection
12
+ registrations, IndexedDB/localStorage, pending inserts/updates/deletes,
13
+ tombstones, anonymous state and service-worker caches. Removing collection
14
+ registrations can delete old stores. Preserve and verify unique pending work
15
+ before stopping its backend, changing registrations or clearing stores.
16
+
17
+ You cannot inspect every disconnected device before cutover. Establish a
18
+ returning-client compatibility/recovery contract and retain the protocol or
19
+ recovery endpoint it needs. Describe the limits for never-returning phones and
20
+ evicted storage; a successful migration on sampled devices cannot prove every
21
+ user's pending work has been recovered.
22
+
23
+ Fence polling/replay before incoming state can overwrite pending work. Copy raw
24
+ requests, source, bases and ownership evidence with resumable checkpoints;
25
+ retain unknown/corrupt records in protected quarantine. A creator field may not
26
+ identify the editor who made a pending change. Do not attach unattributed work
27
+ to the next account that signs in or replay cumulative snapshots as new events.
28
+ A quota/copy failure must prevent destructive cleanup. Test blocked upgrades and
29
+ two tabs.
30
+
31
+ Use durable client storage only where the product needs it. Online
32
+ administration and editing can use server reads/forms. Editing that must survive
33
+ disconnection or restart needs durable drafts; offline mutations also need a
34
+ replay/recovery protocol. Partition client repositories and outboxes by the
35
+ actual owner and target. Keep renewable downloads separate from unique
36
+ drafts/queued work so logout or expiry cleanup cannot destroy the only copy.
37
+ Anonymous adoption requires its own explicit owner/merge policy.
38
+
39
+ If users create related records offline, test a parent and its dependents before
40
+ any server acknowledgement, then reconnect with a rejected parent or changed
41
+ permissions. Preserve stable local IDs and the reference graph across migration
42
+ and retries. Surface blocked dependencies without orphaning, reassigning or
43
+ duplicating children; this case does not require a generic synchronization
44
+ engine.
45
+
46
+ ## Make the offline access policy a product decision
47
+
48
+ Ask whether private downloads expire, what renews access, how revocation and
49
+ sign-out affect them, and whether drafts can reopen or export after access ends.
50
+ No duration from the source app is a default. Cache freshness and authentication
51
+ session expiry are separate from offline authorization.
52
+
53
+ If a bounded permission lease is required, only a fresh authorized server check
54
+ renews it. Network events, reloads, successful session lookup and generic HTTP
55
+ responses are not that check. Distinguish explicit same-account denial from
56
+ network/authentication/protocol failure. Separate read from source/edit
57
+ capability. Server mutations always use current server authorization, not a
58
+ cached lease.
59
+
60
+ Fence late replies using account epoch, target, latest request and version/CAS
61
+ state. Recheck on cold start, foreground/resume, BFCache return and use; a timer
62
+ alone misses suspended tabs. Close views before asynchronous cleanup, revoke
63
+ owned Blob URLs and retire editor/global references. Preserve the latest text,
64
+ including unflushed debounce state, without exposing locked recovery through an
65
+ export or console-handle bypass. A→sign-out→A still needs a new epoch.
66
+
67
+ Prove deletion with a nonempty starting state. For image revocation, record a
68
+ rendered cached image and a positive asset count before denying access, then
69
+ verify removal and offline unavailability. A zero asset count after revocation
70
+ proves nothing if the tested publication never included an image.
71
+
72
+ An app-managed lock is not DRM or a trusted clock. A user-controlled device can
73
+ retain/change bytes, and old offline code cannot receive a new expiry policy
74
+ without updating. Storage can be evicted. State the achievable behavior clearly.
75
+
76
+ ## A complete download includes what the renderer actually uses
77
+
78
+ Build manifests from the authorized selected render, using known renderer rules,
79
+ not an arbitrary client list or a regex for every `src`. Preserve exact query
80
+ spelling/order, source path and fragment semantics; one source path can render
81
+ more than once. Enumerated references are not verified bytes, and verified bytes
82
+ are not a complete permission-bound downloadable bundle.
83
+
84
+ Identify whether the normal online reader also requires a published bundle.
85
+ Imported source and visible catalog metadata do not establish reader readiness.
86
+ Schedule the first publication/backfill explicitly in the cutover, using a
87
+ bounded authenticated or approved maintenance path with durable retry
88
+ identities. Where possible, complete it before directing private readers to the
89
+ new runtime; otherwise make the temporary availability gap explicit and keep
90
+ retirement gated on actual online and offline reads of the imported content.
91
+
92
+ A prepared bundle with owned bytes and a valid wire manifest proves local
93
+ consistency, not durable publication or permission. Independently enumerate the
94
+ rendered content and require an exact complete occurrence-to-asset mapping. Bind
95
+ delivery separately to the account, request, current selected-content descriptor
96
+ and exact manifest hash; a parser's success cannot renew an authorization lease.
97
+ Copy expected bindings, including nested values, before asynchronous hashing or
98
+ I/O, and return an independent immutable result. Test caller mutation across the
99
+ await with the native browser crypto boundary as well as deterministic tests.
100
+
101
+ Reserve stable bundle and asset identities before durable writes, persist them
102
+ with the publication intent, and reuse them after an unknown acknowledgement.
103
+ Creating fresh IDs is a new operation, not recovery of an uncertain one. Recheck
104
+ current selection and permission when publishing after provider work. An
105
+ in-memory preparer accepting retry IDs is a useful foundation; it does not
106
+ establish durable intent recovery or prove the publisher's behavior.
107
+
108
+ Keep an acknowledged create or save separate from its follow-up publication. If
109
+ the primary write commits and publication fails or becomes unavailable, retain
110
+ the write receipt, show the content as saved with publication pending, and
111
+ persist the exact publication request for retry. Reuse its identity after
112
+ uncertain outcomes. Only a terminal result whose contract explicitly permits
113
+ renewal may authorize a replacement publication identity. That replacement must
114
+ remain bound to the original write receipt, current revision, actor and
115
+ permission while preserving the earlier result as evidence.
116
+
117
+ When publication spans object storage and SQL, reserve the immutable operation,
118
+ payload/policy binding and exact owned destinations together before provider
119
+ writes. A replacement worker needs a new fenced claim over the same intent; an
120
+ old worker cannot finish or release that replacement's work. A claim valid at
121
+ transaction entry can expire during awaited SQL statements. Define the clock
122
+ boundary, check after the last awaited mutation while rollback is still
123
+ possible, and test expiration and clock regression at those awaits on the actual
124
+ database. Do not claim that an application clock check proves the database
125
+ commit instant.
126
+
127
+ Commit verified object receipts, completion evidence and the published marker
128
+ atomically. Retain completion evidence independently if published content may be
129
+ deleted; replay must not reinterpret a deleted completed operation as pending.
130
+ Test empty bundles too: asset rows cannot serve as completion evidence when no
131
+ assets ever existed. A current-access reader needs one consistent authorized
132
+ snapshot of the selected content and completed evidence. Its internal storage
133
+ descriptor is not a browser capability; a transport still must enforce current
134
+ permission around byte retrieval. Generic missing or failed reads are not an
135
+ authoritative revocation result.
136
+
137
+ Account for static aliases, legacy uploads, inline data, external images,
138
+ generated output, SVG references and fonts. Keep failures explicitly incomplete;
139
+ publish Ready only after every required byte and manifest binding is verified
140
+ and installed atomically. A later check for new content must not extend an old
141
+ bundle's lease. Fetch/decode outside IndexedDB transactions, then perform a
142
+ short atomic swap guarded by the still-current account/check.
143
+
144
+ Use immutable byte snapshots with size/digest/type/validator provenance.
145
+ Metadata alone does not retain a usable capture: give bytes explicit ownership
146
+ and disposal, budget copies and verify their size/digest and matching validator
147
+ semantics. A derived plan must own its copies if it is to survive disposal of
148
+ its source catalog. Conversely, disposing a catalog cannot erase copies already
149
+ returned. Missing or disposed bytes remain incomplete even if their metadata
150
+ still exists.
151
+
152
+ Decode inline transport separately from validating the image. Native metadata
153
+ does not prove every frame is valid; malformed containers, decompression
154
+ resources, timeouts and actual cancellation need bounded checks. SVGs have
155
+ resource graphs, styles, inheritance and embedded images; preserve originals
156
+ while validating a closed supported profile, and report its rendering/memory
157
+ limits honestly.
158
+
159
+ Acquire external references under the app's explicit acquisition policy. For a
160
+ fixed migration corpus, bind the reviewed references and expected digests. For
161
+ authorized dynamic capture, enforce the approved URL/provider policy and record
162
+ the first verified capture's size and digest as immutable provenance. A hostname
163
+ or path prefix grants no broader authority unless that scope is deliberately
164
+ part of the policy; unsupported local routes must not fall through into external
165
+ fetching. Forward no ambient credentials. Bind connections to checked public
166
+ addresses while preserving hostname/certificate verification and the explicit
167
+ redirect policy. Budget the whole request, including DNS, headers and
168
+ success/error bodies; cancel the actual resolver/streams and fence late results
169
+ rather than only timing out the caller's promise. Provider headers are claims,
170
+ not content authority: validate actual bytes against size limits and detected
171
+ format, and compare expected sizes and digests when prior evidence exists.
172
+
173
+ Bind replacement provenance to both the exact original and acquired references,
174
+ the acquisition policy and the representation. Keep original query spelling,
175
+ fragments and explicit display sizing unchanged. Acquired raster dimensions
176
+ describe its pixels; do not use them to overwrite explicit layout properties.
177
+ Where layout relies on intrinsic dimensions, compare that behavior too. A
178
+ replacement is not byte parity with an unavailable original.
179
+
180
+ Generated graphics need a closed props/query contract and explicit font
181
+ evidence. Immutable representation identity must include the normalized request,
182
+ generator/ font provenance and digest of the final returned bytes. Source
183
+ identity alone can alias different images when reflection, sizing or
184
+ output-format conversion occurs after source generation.
185
+
186
+ `image.decode()` may finish before an SVG image's embedded fonts settle; the
187
+ parent document's font readiness or preloading does not establish the image
188
+ document's readiness. Test immediate first and repeated offline renders from
189
+ fresh image URLs/contexts. Fixed sleeps or a warm successful paint are not a
190
+ readiness contract. Choose and validate an explicit faithful representation:
191
+ outlining text can remove font-loading races but also change intrinsic sizing,
192
+ geometry, shaping, navigation links or selectable/accessibility text. Stable
193
+ repeated pixels do not prove fidelity. Use accepted fixtures for the writing
194
+ systems and symbol groups actual callers expose; a nonempty Latin rendering can
195
+ pass while other glyphs disappear. Preserve original source/provenance and
196
+ review sizing, layout and document semantics before adopting a derivative or
197
+ changing the rendering surface. The interactive component and its live export
198
+ controls can retain their own text/link behavior independently of an image
199
+ representation.
200
+
201
+ Test cold offline deep links with HTTP cache disabled, real IndexedDB and the
202
+ intended worker behavior. Separate worker tests from network-mocked tests:
203
+ workers can bypass request interception. Verify deployment-specific asset URLs
204
+ and update consent across two builds. Generic navigation caches can retain
205
+ authenticated HTML/RSC. In an RSC/PWA app, prefer an anonymous offline shell
206
+ with deliberate gated payload storage; other architectures need an equivalent
207
+ separation from automatically cached personalized responses. Verify owned
208
+ old-cache cleanup and in-memory router state too.
209
+
210
+ External deployment protection can prevent that anonymous shell from installing:
211
+ the worker's credential-omitting warm request may receive a login redirect even
212
+ while the operator's tab is authenticated. Probe every required shell without
213
+ cookies or bypass credentials, then verify the browser has an active
214
+ registration and controller and passes a normal offline reload. Do not put a
215
+ protection token in worker code or cache credentialed private HTML to make the
216
+ check pass.
217
+
218
+ ## Preserve legacy delivery; validate new uploads separately
219
+
220
+ Inventory actual provider, bucket, object key, public URL and MIME precedence.
221
+ An S3-compatible endpoint is not proof of AWS semantics or physical region. When
222
+ buckets are scoped to an account, bind persisted provider identity to that
223
+ account origin as well as bucket/key. A configuration change must not
224
+ reinterpret an old destination in another account. Local namespace checks do not
225
+ prove privacy. Probe canonical resource addresses: a bucket path in an old
226
+ endpoint can also become part of its actual object key. A denied/unsupported
227
+ policy request does not prove privacy or absence of configuration. Verify object
228
+ bytes as well as metadata; neither is an object-body backup.
229
+
230
+ A foreign key to migration provenance does not prove that the current file's
231
+ digest, size, MIME or location still agrees with that provenance. Before
232
+ provider I/O, compare the relevant current facts with the preserved source,
233
+ reusing the reviewed import mapping when possible. Validate the entire bounded
234
+ batch before its first request, including missing entries that array helpers can
235
+ skip.
236
+
237
+ Bound the SDK's error-response handling as well as successful file streams. Some
238
+ SDKs consume error XML before returning control, outside the application's
239
+ normal body reader. Verify the actual installed transport's error/redirect
240
+ paths, deadlines and late-stream cleanup; a timeout wrapper alone does not bound
241
+ bytes already being buffered by the SDK. Inspect errors after SDK processing:
242
+ middleware can decorate even an application's custom error with raw provider
243
+ diagnostics. Recreate an outward error from an approved code projection instead
244
+ of rethrowing that decorated object.
245
+
246
+ Do not infer ownership or privacy from embedded URLs. New attachment authority
247
+ may require both an explicit parent link and occurrence in the authorized
248
+ render; source-preview access can differ. Preserve historical public links and
249
+ supported legacy formats according to the agreed contract even if new uploads
250
+ are stricter.
251
+
252
+ For files above the platform request-body limit, use direct private staging plus
253
+ server finalization. Verify provider-enforced signed size, checksum and exact
254
+ headers using owned probes and real browser/CORS behavior. Read/decode bounded
255
+ staging bytes, snapshot those bytes, then write that exact snapshot
256
+ conditionally; copying a mutable staging object after validation races
257
+ replacement.
258
+
259
+ When a storage receipt asserts exact byte parity, read back and verify bytes and
260
+ immutable provenance after conditional writes, including success and conflict.
261
+ An acknowledgement or ETag alone does not establish the claim. Keep stable
262
+ operation/object identity in immutable metadata and replaceable worker claims in
263
+ verification receipts, so a new worker can verify an earlier worker's object.
264
+
265
+ Keep provider I/O outside SQL. Recheck identity, grants and worker claim before
266
+ publishing file/link/receipt atomically. Abort is not proof that a provider
267
+ rolled back. Preserve an uncertain operation and reconcile only its own verified
268
+ object; do not overwrite/delete an unknown collision. Keep capabilities out of
269
+ source, receipts, logs and offline bundles. Bound memory and concurrency using
270
+ the actual native decoder, not only compressed upload size. If an aborted or
271
+ timed-out PUT still owns its input buffer, retain that snapshot and its
272
+ concurrency slot until the underlying send settles; premature wiping can corrupt
273
+ a late successful write. Per-adapter bounds are not process or fleet bounds. For
274
+ authorized reads, recheck current selection and access after GET, discard denied
275
+ or changed bytes, and handle late completion with the same ownership rules.
276
+
277
+ When retiring a browser synchronization engine, fence future network calls
278
+ synchronously before awaiting its population event or a new database open. Wait
279
+ for already-started calls to settle without treating a failed network response
280
+ as a permanent recovery failure. Preserve signed-in pending work as well as
281
+ anonymous work; server backups do not contain either kind of unsent change.
282
+ Verify the new copy after commit before stopping subscriptions or clearing the
283
+ old records. Keep retries fenced after quota, serialization or storage failures.
284
+
285
+ Exercise the installed client's actual update method when testing recovery.
286
+ Before-images can share nested objects and dates with the pending document.
287
+ Plain JSON can silently lose undefined/nonfinite values or type information,
288
+ while an overstrict cycle check can reject ordinary shared references. Prefer an
289
+ existing, verified typed serializer; preserve raw corrupt storage strings as
290
+ opaque evidence. Copy own keys without invoking prototype setters and reject
291
+ unsupported values before certifying preservation. Omit only runtime metadata
292
+ whose shape and use have been demonstrated, not every field with a familiar
293
+ name.
294
+
295
+ Trace one imported record through the actual reader before declaring the storage
296
+ migration ready. A preserved compiled archive is not a published offline bundle.
297
+ Wire resumable publication of the selected output, including image acquisition
298
+ and immutable object receipts, before switching readers that require manifests.
299
+ Do the same for newly saved revisions. Preserve anonymous public reads and old
300
+ deep links explicitly; account-bound private leases must not accidentally make
301
+ public content require a login. Give users an offline way to find their
302
+ downloads.
303
+
304
+ Provider administration and application object access may use different
305
+ credentials. Verify the authenticated account against the existing deployment,
306
+ then use separate bucket-scoped credentials for Production and Preview. For new
307
+ private Files storage, keep public access disabled and browser upload origins
308
+ explicit. Preserve existing public distribution until its separately reviewed
309
+ replacement is accepted. Successful bucket creation does not establish usable
310
+ signing credentials, application access, database isolation or complete
311
+ migration readiness.
312
+
313
+ For private browser-direct R2 access, bind a reviewed CORS document to the exact
314
+ account and environment bucket. Allow only the stable application origin and the
315
+ methods and headers the upload protocol requires; an ephemeral Preview URL does
316
+ not justify a wildcard origin. Read back the canonical policy, confirm unrelated
317
+ buckets stayed unchanged and exercise a real browser preflight after the stable
318
+ origin exists.
319
+
320
+ For legacy storage relocation, inspect production environment configuration and
321
+ an actual provider read before inferring a provider or object key from variable
322
+ names. An AWS-named credential can address another S3-compatible provider, and
323
+ an old endpoint containing a bucket path can have produced prefixed object keys.
324
+ Inventory the complete bucket, including objects without database rows. Preserve
325
+ the original import snapshot and record verified destination mappings
326
+ separately; trace both public compatibility readers and publication/background
327
+ readers before retiring the source. Copy with conditional writes, compare actual
328
+ destination bytes and application MIME metadata, and prove a rerun reuses
329
+ matching objects. Repeat reconciliation after fencing writers; a preliminary
330
+ copy is not cutover.
331
+
332
+ For separate environment credentials, an own-bucket PUT/GET plus a cross-bucket
333
+ denial on a known existing synthetic object gives concrete isolation evidence.
334
+ It does not prove the full token policy. Remove owned test objects and verify
335
+ cleanup. If write-only secrets need a local handoff for subsequent approved
336
+ work, use a private file with an explicit cleanup point rather than asking the
337
+ operator to enter them again or pretending the provider can return them later.
338
+
339
+ ### Verify the navigation and UI that consume durable state
340
+
341
+ A cached offline shell is useful only if the actual request handler serves it
342
+ for a first direct offline visit. Test the installed service-worker routing,
343
+ including HTML versus RSC/prefetch requests, instead of testing only the cache
344
+ helper. A private route may fall back to an anonymous shell, never a previously
345
+ cached credentialed document. Bind rendered state to the current resource and
346
+ account before effects run so navigation cannot briefly show the preceding
347
+ private item.
348
+
349
+ Repository notifications must not reset an active task. Keep the same resource
350
+ snapshot visible while refreshing it; unmounting a quiz or editor after every
351
+ save can discard session state even when every database transaction is correct.
352
+ Show storage failures explicitly instead of leaving an indefinite loading state.
353
+
354
+ An upload receipt, a readable source locator and a published offline dependency
355
+ are separate steps. Trace a newly uploaded image all the way into editable
356
+ source, authorized online rendering and the completed offline bundle before
357
+ claiming the media feature is activated. Preserve legacy public locators through
358
+ a narrowly scoped archived metadata lookup; do not route new private uploads
359
+ through it.
360
+
361
+ Assembling a permission grant and a bundle across asynchronous reads creates a
362
+ revocation window. Recheck the current grant after the bundle lookup, then pair
363
+ the response with that grant's exact resource/revision identity. An initial
364
+ authorization check alone does not cover later provider or database waits.
365
+
366
+ HTTP clients can expose decompressed body bytes while preserving the compressed
367
+ wire `Content-Length`. Bound the stream actually consumed and verify its decoded
368
+ length and digest against the manifest; do not reject a valid compressed image
369
+ merely because the wire length differs. Include a real compressed HTTP response
370
+ when this boundary matters, plus an oversized decoded-body rejection.
371
+
372
+ Inspect the installed legacy database's upgrade behavior before opening it.
373
+ Registering only the new application's collections can make an old client delete
374
+ unrecognized object stores. Inventory before every upgrade, including recursive
375
+ reopens, and fail closed if another tab changes the schema between inspection
376
+ and open. A timed-out open may still be pending; retry a settled failure without
377
+ starting competing opens. Test the real browser adapter and the Node export:
378
+ client components can still import their dependencies during server
379
+ prerendering.
380
+
381
+ Server-side rendering helpers may load fonts, WASM and public files dynamically.
382
+ A successful local build does not prove those files enter a serverless artifact.
383
+ Inspect the affected route's file trace or packaged output and include only its
384
+ required assets. Bound dependent backfill reads as well as the parent page; a
385
+ small page of records can otherwise fetch an unbounded operation history. Resume
386
+ only intents owned by the authorized actor and matching the current selection.
387
+
388
+ When persisted validation identities include source hashes, separate runtime
389
+ policy from unrelated response types. A type-only edit can invalidate historical
390
+ evidence despite unchanged validation semantics. Trace the exact source delta
391
+ before rotating a policy identity; preserve compatible readers deliberately.
392
+
393
+ Treat retained compilers and renderers as a joint compatibility boundary. Their
394
+ established output may be broader than a newer shared TypeScript interface.
395
+ Exercise representative real documents before adding runtime validation or
396
+ rewriting trees to satisfy types. A narrow documented type bridge can preserve
397
+ the actual format while its redesign remains a separate task.
398
+
399
+ Permission refresh must not silently erase an unsent form. Retain its values
400
+ under the previously verified owner, hide them while authorization is
401
+ unresolved, and restore them only after the same owner and selected scope are
402
+ authorized. Late compilation, save, upload and publication callbacks must also
403
+ belong to the current editor lifecycle before changing visible state.