@gadicc/loom 1.27.0 → 1.29.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,251 @@
1
+ # Identity and data
2
+
3
+ ## Inspect each auth starting point
4
+
5
+ Distinguish Gongo's own auth, NextAuth/Auth.js with a custom Mongo/Gongo
6
+ adapter, and the intended Loom auth implementation. Inventory actual provider
7
+ strategies, credential verification, cookies, session expiry, account-linking
8
+ rules, embedded service identities and separate account collections. Old
9
+ strategy configuration can be stored in a collection named `accounts` without
10
+ being a user account.
11
+
12
+ Include partially migrated apps that already run Better Auth on Mongo while
13
+ retaining legacy field mappings, cookie names or NextAuth-shaped client APIs.
14
+ Trace route handlers, adapters, hooks, bundler aliases and session verification
15
+ before classifying the starting point. A `next-auth` import or cookie name does
16
+ not establish that NextAuth owns authentication. Preserve required legacy
17
+ profile and ID projections during persistence changes. Test the current
18
+ auth-to-Gongo boundary against expired, malformed and account-switched sessions;
19
+ stripping a cookie signature or forwarding a token is not itself verification.
20
+ Keep the existing verified auth authority when it supports the migration.
21
+
22
+ Gongo has supported a trusted request principal and a NextAuth session-token
23
+ alternative. That makes a staged bridge plausible, but inspect the installed
24
+ transport and database adapter before relying on it. In the source migration, an
25
+ absent trusted principal fell through to a body/cookie token lookup that did not
26
+ itself verify expiry. The fix supplied the verified server identity and an
27
+ explicit anonymous principal, then tested the actual transport's fallback paths.
28
+ This is a regression to look for, not a bridge to paste into every Gongo
29
+ version.
30
+
31
+ Do not infer password compatibility from a method name or old comments. The
32
+ inspected Mongo adapter's password method throws despite retaining commented
33
+ bcrypt code. An older app may have a different implementation. Inspect its exact
34
+ hash/verifier and session lifecycle; prove any compatible verification bridge
35
+ with synthetic accounts or plan an explicit reset/reauthentication transition.
36
+ No password migration was exercised in the source modernization.
37
+
38
+ A bridge should keep the existing authoritative identity/storage until its
39
+ dependents are ready. Adapt verified identity at one server boundary and test
40
+ anonymous, malformed, expired and account-switched requests. Never accept a body
41
+ user ID as authentication. An `expectedActorId` is only an account-switch
42
+ precondition against a separately verified current actor.
43
+
44
+ Inspect what a "fresh session" helper actually caches. Bypassing a signed cookie
45
+ cache can still leave request-level memoization in place. When a boundary checks
46
+ again after provider I/O, use a fresh database read on each call and verify that
47
+ session revocation between calls is observed. Keep session renewal and ordinary
48
+ UI caching separate from that authorization read. Exercise the actual runtime
49
+ auth factory and cookies against the imported identities; a copied test-only
50
+ configuration can pass while runtime linking, transaction or cookie settings
51
+ drift. Stub only the external provider boundary, never expose that bypass in
52
+ production configuration.
53
+
54
+ Check whether the auth library changes request protections in test mode.
55
+ Exercise the intended origin/CSRF policy in handler tests rather than treating a
56
+ test-only default bypass as evidence about the deployed behavior.
57
+
58
+ Exercise failed writes as well as successful token encryption: adapter errors
59
+ can embed raw query parameters, including credentials, in otherwise ordinary
60
+ error objects. Verify the actual logger and HTTP response at that failure
61
+ boundary and keep safe diagnostic events without forwarding raw
62
+ provider/database objects.
63
+
64
+ ## Allocate canonical identities once
65
+
66
+ Follow the target Loom/schema contract for canonical IDs; this modernization
67
+ uses UUIDv7 in SQL and relevant Node/browser allocation. Do not turn provider
68
+ subjects, content hashes, slugs or static content keys into generated IDs.
69
+ Verify the required generation function in both the target database and test
70
+ harness; silently substituting another UUID version changes the contract.
71
+
72
+ Preserve external identities in the provider's own namespace and value domain. A
73
+ forum's numeric user ID needs the reviewed forum origin as part of its identity;
74
+ later configuration must not reinterpret it against another server. Bind both
75
+ imports and runtime lookups to that namespace. Preserve numeric meaning and test
76
+ exact driver round trips at the supported limit; do not coerce larger IDs into
77
+ unsafe JavaScript numbers or replace them with local UUIDs. Keep the canonical
78
+ local owner as a separate link and reject ambiguous ownership within a
79
+ namespace.
80
+
81
+ Preserve aliases by source system, entity/collection, legacy BSON type and exact
82
+ value. An ObjectId and a string with identical characters are not globally
83
+ equal. Allow only reviewed field-specific reference conversions, rejecting
84
+ ambiguity. Allocate and persist aliases transactionally before importing
85
+ dependents; reruns and resumes reuse them. Multiple source aliases may
86
+ intentionally map to one canonical entity, so uniqueness on the destination
87
+ alone is usually wrong.
88
+
89
+ Reconcile provider/subject identities across embedded and separate account
90
+ shapes. Changed email must not create a duplicate of an existing provider
91
+ identity; equal email must not silently merge different people. Retain verified
92
+ and secondary email evidence, nullable historical dates and original names while
93
+ normalizing required adapter fields. Keep application grants separate from
94
+ provider profiles. Import old tokens or sessions only for an established need
95
+ and proven compatibility; accepted one-time reauthentication can simplify that
96
+ boundary but is an app-specific decision.
97
+
98
+ ## Preserve facts before correcting them
99
+
100
+ Decode protected real data read-only and classify every record. Synthetic tests
101
+ should cover observed shapes without publishing personal data or source.
102
+ Preserve missing fields, nulls, typed dates, line endings, leading BOM, Unicode,
103
+ ordered arrays and cumulative totals where meaningful. Avoid fabricating
104
+ historical review events, creators, dates, grants or defaults to satisfy a
105
+ schema. Keep original BSON and protected provenance: JSON/EJSON archives are not
106
+ wire bytes.
107
+
108
+ Check the decoder's numeric promotion explicitly. Different BSON integer/double
109
+ tags can become the same JavaScript value. A verified closed source profile can
110
+ retain frame/type digests, prove exact typed decode/re-encode first, then
111
+ project only supported values for existing mappers. Unsafe integers, duplicate
112
+ fields, normalized array indices or unsupported types must not silently
113
+ disappear. Test this on the actual corpus before assuming a BSON library is
114
+ wire-lossless.
115
+
116
+ Capture an explicit pinned dump, not whichever directory is newest. Verify its
117
+ layout and actual compressed hashes, bound inflated bytes and record counts, and
118
+ refuse unexpected files or symlinks. Metadata/index definitions are evidence to
119
+ inspect, not commands to execute during import. Recheck the source after pure
120
+ preparation, before returning a usable plan. Cancellation must settle native
121
+ decompression before its owned input bytes are wiped; deadlines on ordinary
122
+ filesystem calls may remain cooperative and should be described accurately. On
123
+ POSIX, opening an unexpected FIFO can hang before a regular-file descriptor
124
+ check. Use a nonblocking open before that check; a path-only check leaves a swap
125
+ race. A bounded FIFO regression should release the old implementation on failure
126
+ so the test itself cannot hang indefinitely.
127
+
128
+ Unknown fields, orphan references, duplicate natural keys and unrepresentable
129
+ text need explicit dispositions. A reviewed exception should identify exact
130
+ source facts/fingerprint and fail when input changes; do not compute its
131
+ approval from arbitrary input during import. Preserve disputed rows in a
132
+ protected archive instead of silently dropping or summing snapshots. Repairs are
133
+ separate product decisions unless their intent is established.
134
+
135
+ A specialized mapper's success is not a disposition for every source field. An
136
+ auth adapter can correctly omit a field still consumed by a separate product
137
+ integration. Compare preserved source fields against all live consumers and
138
+ require an explicit target, archival-only decision or retirement for each used
139
+ field; use an app-owned projection when it is outside the shared auth contract.
140
+
141
+ Put important parent/version/source relationships in SQL constraints, including
142
+ composite foreign keys where one ID cannot prove ownership. Review generated
143
+ migration ordering on a real database. PGlite is useful for repositories but
144
+ does not prove target extensions, driver error shapes, collation, concurrency or
145
+ exact text round trips. The source migration found both a BOM decoding
146
+ difference and different uniqueness-error property names across drivers.
147
+
148
+ Compute complete expected rows before writing, including every column and tables
149
+ that should remain empty. Require explicit IDs and required bookkeeping values;
150
+ do not let SQL defaults allocate them on retries. Compare both missing and extra
151
+ rows with multiplicity. For suitable PostgreSQL schemas, typed expected rows and
152
+ bidirectional `EXCEPT ALL` can keep comparison in SQL: JSONB object-key order
153
+ stays semantic while text bytes, JSON null versus SQL NULL, timestamp
154
+ microseconds and high-precision JSONB decimals remain distinguishable.
155
+ Converting actual values through JavaScript first may silently round away
156
+ differences. Snapshot the expected values before awaits, and only return their
157
+ precomputed fingerprint after equality. The caller still owns schema/target
158
+ validation, transaction locks and deadlines; sequential unlocked table
159
+ comparisons do not prove one snapshot.
160
+
161
+ For a small bootstrap import, one durable singleton checkpoint and one atomic
162
+ application transaction can be simpler than resumable row batches. A transaction
163
+ lock alone does not reserve a run between preparation and application: constrain
164
+ the singleton in SQL. Bind the exact saved payload and expected-row hash; keep
165
+ completion evidence separate from domain foreign keys so later deletions cannot
166
+ erase it. Match the codec's finite timestamp domain in SQL too, since PostgreSQL
167
+ can otherwise store infinity. Compare every historical migration hash/timestamp,
168
+ not just the newest entry; a valid journal still does not rule out catalog
169
+ drift.
170
+
171
+ For a fenced import, compare actual schema definitions with a separately
172
+ reviewed fresh-migration baseline for the intended engine and environment.
173
+ Include constraints, defaults, indexes, triggers, policies, enum/function
174
+ definitions and relevant extension/locale settings. Exclude incidental OIDs and
175
+ row statistics; do not normalize meaningful owner, extension or engine
176
+ differences to force a match. Capturing the target and immediately trusting that
177
+ snapshot approves whatever drift is already there. A catalog digest is
178
+ consistency evidence, not authorization or authentication of a provider
179
+ destination.
180
+
181
+ When using unqualified PostgreSQL tables, put `pg_temp` explicitly after
182
+ intended schemas in a fixed search path; leaving it out implicitly searches
183
+ temporary relations first. A pooled connection can otherwise shadow a durable
184
+ checkpoint with a same-name temporary table. Qualify lock and reconciliation
185
+ targets too. Prove competing-importer and ordinary-writer behavior with separate
186
+ real database connections. Chunk statements for parameter limits within the
187
+ chosen atomic transaction; do not accidentally turn statement chunks into
188
+ partial commits. After an uncertain acknowledgement, inspect/retry the same
189
+ saved run. A completed bootstrap retry should verify its baseline and refuse
190
+ later application changes, rather than repair them back to the import snapshot.
191
+
192
+ Select a maintenance connection once and use that same selection for preflight
193
+ and execution; shared runtime and migration resolvers may have different
194
+ precedence. A direct-looking environment variable is not proof of an unpooled
195
+ endpoint. Reject unexpected URL routing/startup options, construct explicit
196
+ driver options and verify certificates/hostnames rather than assuming a driver's
197
+ `require` SSL mode does so. Inspect the installed implementation. Do not
198
+ silently discard a channel-binding requirement the driver cannot implement. Test
199
+ actual driver option resolution against ambient environment overrides and real
200
+ TLS handshakes, keeping synthetic transport evidence distinct from provider
201
+ identity. Exercise each supported address form after driver parsing: DNS names,
202
+ literal IPs, multi-host routing and environment fallbacks can reach different
203
+ TLS identity paths. A trusted certificate must match the selected endpoint, not
204
+ a default hostname. Refuse unsupported routing explicitly instead of claiming
205
+ verification from a successful DNS-only test.
206
+
207
+ Keep import planning pure where it makes decisions easier to review. The
208
+ eventual executor still needs persistent source fingerprints, aliases,
209
+ dispositions, checkpoints and conflict policy. A repeatable in-memory plan with
210
+ disposable IDs is not a resumable importer. Refuse changed source or newer
211
+ target writes unless the chosen reconciliation policy explicitly handles them.
212
+
213
+ A saved prepared plan can be the allocation manifest for a small atomic import;
214
+ it need not have a second competing per-row allocation registry. Include IDs for
215
+ provenance and alias rows as well as primary entities, and materialize required
216
+ bookkeeping dates before saving. Resume the exact payload after apply failure.
217
+ Snapshot source/configuration before invoking injected allocation callbacks.
218
+
219
+ Before applying the final snapshot, recheck its complete file graph and match
220
+ every reviewed exception by typed source identity and source fingerprint rather
221
+ than fresh array position. Allocate canonical IDs once in the durable prepared
222
+ plan. A completed receipt should bind both that allocation and the applied-row
223
+ fingerprint, and an unchanged replay should verify them without allocating
224
+ again. Run additive post-import work only after that completed import evidence
225
+ passes.
226
+
227
+ Verify the checkpoint serializer against real mapper output, including genuine
228
+ Dates, literal date-looking strings, unusual metadata keys and exact source
229
+ archives. A library's special-key restrictions or type annotations can make a
230
+ generic serializer unsuitable. Bound escaped output and structural allocation,
231
+ not only raw string length. Digests prove consistency with trusted expected
232
+ bindings; they do not authenticate a target database or authorize row contents.
233
+
234
+ A strict source profile should still be tested against the protected corpus. The
235
+ combined source pass exposed unused historical profile fields omitted by smaller
236
+ fixtures. Preserve or explicitly retire these fields without giving them new
237
+ login/permission meaning. Report which independent reviews completed and which
238
+ verification was local; do not imply completed review when a worker stopped.
239
+
240
+ For edits, commit revision, selected output, parent CAS state and immutable
241
+ operation receipt together. Retry an uncertain result with the same operation
242
+ and payload. Replays must recheck current access and must not resurrect deleted
243
+ objects or revoked relationships. Keep legacy protocol receipts interpretable;
244
+ do not rewrite an old operation into a new backend/version under its old ID.
245
+
246
+ Treat a cached session as a display hint, not permission to assign durable local
247
+ ownership. Fresh server verification may activate an account. For offline cold
248
+ starts, reopen only the previously verified owner under the application's expiry
249
+ policy; a different cached account must not overwrite that identity. An explicit
250
+ sign-out fence survives restart. Serialize durable account transitions and fence
251
+ late responses so an older activation cannot reopen views after sign-out.
@@ -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.