@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.
- package/README.md +7 -3
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +76 -13
- package/esm/src/next/auth/client.d.ts +28 -0
- package/esm/src/next/auth/client.d.ts.map +1 -0
- package/esm/src/next/auth/client.js +28 -0
- package/esm/src/next/auth/server.d.ts +16 -0
- package/esm/src/next/auth/server.d.ts.map +1 -1
- package/esm/src/next/auth/server.js +15 -3
- package/package.json +6 -2
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +76 -13
- package/script/src/next/auth/client.d.ts +28 -0
- package/script/src/next/auth/client.d.ts.map +1 -0
- package/script/src/next/auth/client.js +32 -0
- package/script/src/next/auth/server.d.ts +16 -0
- package/script/src/next/auth/server.d.ts.map +1 -1
- package/script/src/next/auth/server.js +15 -3
- package/skills/loom-auth/SKILL.md +65 -0
- package/skills/modernize-app/SKILL.md +90 -0
- package/skills/modernize-app/agents/openai.yaml +4 -0
- package/skills/modernize-app/references/architecture-and-characterization.md +205 -0
- package/skills/modernize-app/references/identity-and-data.md +251 -0
- package/skills/modernize-app/references/offline-and-media.md +403 -0
- package/skills/modernize-app/references/rollout-and-shared-work.md +400 -0
|
@@ -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.
|