@gadicc/loom 1.27.0 → 1.28.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -3
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +76 -13
- package/package.json +2 -2
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +76 -13
- package/skills/loom-auth/SKILL.md +32 -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,205 @@
|
|
|
1
|
+
# Architecture and characterization
|
|
2
|
+
|
|
3
|
+
## Establish what exists before replacing it
|
|
4
|
+
|
|
5
|
+
Trace entry points to their actual reads, writes, identity and external effects.
|
|
6
|
+
An empty RPC router can be removed after usage/build checks; a populated one
|
|
7
|
+
needs a caller and behavior migration. Inspect route files before proposing a
|
|
8
|
+
Pages-to-App Router migration. Compare live deployment settings with local
|
|
9
|
+
configuration rather than assuming either mirrors the other.
|
|
10
|
+
|
|
11
|
+
Reference apps provide patterns, not a version set or universal product policy.
|
|
12
|
+
Compare richer behaviors and missing cases. A cache freshness TTL is not an
|
|
13
|
+
authorization lease; a whole-database cleanup helper may destroy an outbox in
|
|
14
|
+
another app. Use Loom's registries when doing shared extraction.
|
|
15
|
+
|
|
16
|
+
Make a small feature matrix with authority, read/write entry points,
|
|
17
|
+
permissions, offline necessity, unsynchronized state and intended replacement.
|
|
18
|
+
Trace code that bypasses a nominal data adapter: auth adapters, uploads, jobs
|
|
19
|
+
and integrations often use the database directly. Identify unused experiments
|
|
20
|
+
separately from active systems. An ingestion target and a retrieval target can
|
|
21
|
+
have drifted; moving the wrong one does not migrate the product.
|
|
22
|
+
|
|
23
|
+
## Pick the smallest useful service boundary
|
|
24
|
+
|
|
25
|
+
For online pages, Server Components can call server query services directly and
|
|
26
|
+
ordinary forms can use authenticated Server Actions. RSC does not provide
|
|
27
|
+
durable client state or replace every transport. Keep versioned callable
|
|
28
|
+
endpoints for offline outboxes, streaming, direct uploads and binary/rendered
|
|
29
|
+
responses. Do not persist deployment-specific Server Action references as
|
|
30
|
+
durable offline commands.
|
|
31
|
+
|
|
32
|
+
When consolidating generated-media routes, derive a closed registry and
|
|
33
|
+
parameter contract from actual callers. Keep old URLs as thin wrappers over the
|
|
34
|
+
shared service. Preserve genuine list-valued parameters, their order and
|
|
35
|
+
meaningful empty values; do not confuse them with repeated scalar keys. A widget
|
|
36
|
+
exporting live client state needs its own server-rendering contract before
|
|
37
|
+
adding its slug.
|
|
38
|
+
|
|
39
|
+
Reuse authorization and domain services across old and new entry points. A
|
|
40
|
+
database transition must not leave old generic mutation endpoints able to bypass
|
|
41
|
+
the new command. Constrain them or migrate coupled callers in the same unit. A
|
|
42
|
+
brief full-snapshot bridge can be simpler than preserving a flawed timestamp
|
|
43
|
+
delta protocol; measure its bounded data size and remember that an omitted item
|
|
44
|
+
does not automatically evict a legacy cache.
|
|
45
|
+
|
|
46
|
+
Separate an operation's protocol version, data schema version, concurrency
|
|
47
|
+
version, compiler identity and output compatibility profile. A compatible
|
|
48
|
+
compiler update should not make older stored output unreadable; a new renderer
|
|
49
|
+
profile requires explicit reader support.
|
|
50
|
+
|
|
51
|
+
## Characterize behavior that the migration could change
|
|
52
|
+
|
|
53
|
+
Prioritize permissions, exact source/data round trips, concurrency, uncertain
|
|
54
|
+
acknowledgements, scheduling boundaries, anonymous adoption, critical form
|
|
55
|
+
values, stream framing and actual rendering. Extract pure logic from
|
|
56
|
+
editor/framework side effects where practical. Do not turn legacy library method
|
|
57
|
+
names into the permanent test interface or preserve an obvious defect as
|
|
58
|
+
required behavior.
|
|
59
|
+
|
|
60
|
+
Use scoped coverage that includes unimported files in selected modules. Describe
|
|
61
|
+
its scope honestly; high coverage of extracted modules is not whole-app
|
|
62
|
+
coverage. Expand it as meaningful boundaries move. Do not weaken assertions or
|
|
63
|
+
thresholds merely to accommodate a dependency upgrade.
|
|
64
|
+
|
|
65
|
+
Use old/new comparisons for scheduling, astronomy, compiler/source maps and
|
|
66
|
+
serialization. Fix clocks/locales/timezones and preserve absent versus zero/null
|
|
67
|
+
states. Test actual controls for partial dates and clearing; a schema test alone
|
|
68
|
+
does not show what a third-party picker submits. Inspect package exports and
|
|
69
|
+
native binaries, not only version ranges.
|
|
70
|
+
|
|
71
|
+
Standalone harnesses should use the package instances and runtime realms of the
|
|
72
|
+
boundary they exercise. CJS/ESM entry points or duplicate installations can
|
|
73
|
+
create distinct class identities and fail `instanceof` for otherwise equivalent
|
|
74
|
+
values. Diagnose a harness mismatch before weakening validation. If mixed
|
|
75
|
+
instances occur in the supported runtime, treat that as a compatibility issue to
|
|
76
|
+
resolve and test; changing only the fixture would hide the problem. Check the
|
|
77
|
+
runtime export shape too: a standalone CJS loader can expose an ESM schema's
|
|
78
|
+
re-exports beneath a default namespace. Match the supported loader before
|
|
79
|
+
changing app exports to satisfy the harness.
|
|
80
|
+
|
|
81
|
+
Real browser checks matter for contenteditable/CodeMirror, hook-driven
|
|
82
|
+
rendering, selection, clipboard, service workers, IndexedDB and multi-tab
|
|
83
|
+
lifetimes. Keep known baseline failures identifiable, then compare old/new
|
|
84
|
+
behavior. A documented hook-order workaround may require retaining the current
|
|
85
|
+
renderer and disabling a new compiler optimization until its architecture is
|
|
86
|
+
deliberately changed.
|
|
87
|
+
|
|
88
|
+
Widget mocks must preserve lifecycle boundaries relevant to the failure. An
|
|
89
|
+
eager editor mock can hide a lost source update before the real view mounts.
|
|
90
|
+
Verify initial text and preview after delayed creation, and that a late view
|
|
91
|
+
cannot restore content after access is locked. Inspect whether controlled value
|
|
92
|
+
updates emit the same change callback as user input before relying on that
|
|
93
|
+
callback for compilation or draft persistence.
|
|
94
|
+
|
|
95
|
+
## Choose the acceptance environment early
|
|
96
|
+
|
|
97
|
+
Inspect Loom and the reference apps for developer test-user flows before asking
|
|
98
|
+
the operator to repeat long multi-account journeys on Preview. Automate ordinary
|
|
99
|
+
permissions, forms, account switching and offline behavior against isolated
|
|
100
|
+
local data. Keep a smaller deployed pass for actual OAuth callbacks, platform
|
|
101
|
+
packaging, database integration and object-storage behavior that local services
|
|
102
|
+
cannot prove. Synthetic sessions can prove the application's authorization and
|
|
103
|
+
lifecycle contracts, but they cannot prove provider consent, callback
|
|
104
|
+
registration, cookie behavior or account linking. Keep the real OAuth journey as
|
|
105
|
+
its own deployed gate.
|
|
106
|
+
|
|
107
|
+
Keep developer login and production-build test sessions separate. Shared
|
|
108
|
+
developer login can own explicit opt-in, local request checks, fixed identity
|
|
109
|
+
selection and cookie forwarding; the app owns identity persistence and
|
|
110
|
+
permission grants. An identity named "admin" must not silently bypass a separate
|
|
111
|
+
grant fixture. Follow the installed `loom-auth` guidance when its shared helper
|
|
112
|
+
is available.
|
|
113
|
+
|
|
114
|
+
For service-worker acceptance, use the app's production build when development
|
|
115
|
+
mode disables the worker. An auth library's official test helper can create real
|
|
116
|
+
sessions through a separate command without enabling a deployed test-login
|
|
117
|
+
route. Bind the command to synthetic targets, validate sessions with the actual
|
|
118
|
+
runtime auth configuration, and keep browser storage-state files private and
|
|
119
|
+
ignored.
|
|
120
|
+
|
|
121
|
+
Exercise real local storage protocols where practical, including conditional
|
|
122
|
+
write retries and subsequent reads. A passing local adapter does not prove cloud
|
|
123
|
+
CORS, credentials or exact provider behavior. Keep any local transport exception
|
|
124
|
+
explicit and scoped; preserve the cloud adapter's authorization and validation.
|
|
125
|
+
|
|
126
|
+
Test cold loading and reconnect separately from steady-state requests. A private
|
|
127
|
+
view can register while account verification is still in progress, miss its
|
|
128
|
+
first permission check, and later display a cached grant without checking
|
|
129
|
+
revocation. Coalesce readiness retries without looping on the state changes
|
|
130
|
+
caused by those same requests. Review every caller of shared identity
|
|
131
|
+
activation, since an older verification may change local authority before a
|
|
132
|
+
newer check rejects it as stale. Also interrupt an already-started permission
|
|
133
|
+
request with account activation: readiness gating alone does not repair a
|
|
134
|
+
cancelled request. Exercise registration of already-cached resources with the
|
|
135
|
+
real coordinator: asynchronous discovery can invalidate a request before its
|
|
136
|
+
first network call. A lock reason may be shared by that discovery and the
|
|
137
|
+
request's own successful cache update. Track whether the permission response was
|
|
138
|
+
accepted, and retry pre-acceptance cancellation without turning accepted cache
|
|
139
|
+
changes or ordinary network failures into a loop. When replacing awaited work
|
|
140
|
+
with queued callbacks, preserve ordering required by later save, publication or
|
|
141
|
+
cleanup operations. Update tests so their promises are actually in flight before
|
|
142
|
+
exercising cancellation or sign-out.
|
|
143
|
+
|
|
144
|
+
When a browser session closes without evidence, inspect driver stderr before
|
|
145
|
+
diagnosing an application crash or retrying. Restricted script contexts may omit
|
|
146
|
+
ordinary globals, and an uncaught event-listener error can terminate the driver.
|
|
147
|
+
|
|
148
|
+
## Upgrade tooling without bundling a product rewrite
|
|
149
|
+
|
|
150
|
+
Follow `upgrade-deps`; re-query supported versions and migration guidance when
|
|
151
|
+
the work happens. Align actual executing Node/Deno, package-manager pins, CI and
|
|
152
|
+
deployment targets. Preserve intentional loaders and build modes while moving
|
|
153
|
+
framework/runtime/adapter families. Read installed framework docs where
|
|
154
|
+
available. Migrate formatter defaults deliberately and separate broad formatting
|
|
155
|
+
from behavior changes; lint-driven React key changes can alter state.
|
|
156
|
+
|
|
157
|
+
After dependency patches or code generation, inspect the artifact actually
|
|
158
|
+
served. A package file can be correct while an incremental framework cache still
|
|
159
|
+
emits old code. Use clean generated output when evidence calls for it; do not
|
|
160
|
+
delete user data or lockfiles to make verification pass. Match source/artifact
|
|
161
|
+
identities between isolated tests and the integrated app.
|
|
162
|
+
|
|
163
|
+
A repository alert banner is not a dependency audit result: its count can differ
|
|
164
|
+
from the API and can outlive manifests removed from the default branch. Resolve
|
|
165
|
+
alerts against the current default-branch manifests and lockfile, then trace
|
|
166
|
+
each advisory through the installed dependency path to its actual input and
|
|
167
|
+
sink. An unreachable trigger can justify scheduling a patch after a release, but
|
|
168
|
+
it is not security clearance for the dependency or for unrelated alerts.
|
|
169
|
+
|
|
170
|
+
When diagnosing a Vercel prebuilt deployment mismatch, rebuild from a fresh real
|
|
171
|
+
dependency tree. Reused dependencies can conceal packages or files that the
|
|
172
|
+
declared install and deployment artifact do not contain. When the installed CLI
|
|
173
|
+
supports it, use `vercel build --standalone` to inline external file references,
|
|
174
|
+
then prove every packaged path remains inside the standalone output root.
|
|
175
|
+
Inspect the complete upload graph rather than only regular files: follow
|
|
176
|
+
symlinks and resolve `FileFsRef` and `filePathMap` entries to their final
|
|
177
|
+
packaged targets. A successful build or upload summary does not establish that
|
|
178
|
+
this graph is complete. Nor does enumerating every traced edge prove the tracer
|
|
179
|
+
discovered data loaded from a runtime-computed path. For dynamic fonts, native
|
|
180
|
+
data or similar resources, verify the physical packaged file and execute the
|
|
181
|
+
built route that opens it.
|
|
182
|
+
|
|
183
|
+
For native/WASM resources, exercise the built public route and inspect
|
|
184
|
+
deployment asset traces. A loader working in unit tests can be rewritten by the
|
|
185
|
+
bundler or retain a build-machine path. Verify every wrapper carries the
|
|
186
|
+
required server assets, and exercise repeated calls in one process: shared
|
|
187
|
+
initialization can fail even when each isolated test succeeds.
|
|
188
|
+
|
|
189
|
+
Next's NFT trace can name an asset through a pnpm package symlink while the
|
|
190
|
+
final standalone artifact omits its physical target. Check the actual packaged
|
|
191
|
+
and deployed file, then exercise native/WASM initialization; a trace entry alone
|
|
192
|
+
proves neither inclusion nor loadability.
|
|
193
|
+
|
|
194
|
+
An RSC page can carry a runtime exception with HTTP 200. Inspect the decoded RSC
|
|
195
|
+
result and runtime error. Under current Next, do not pass the Next `Link`
|
|
196
|
+
function through MUI's `component` prop across a server/client boundary;
|
|
197
|
+
instantiate that composition in a client component. Client-only usage remains
|
|
198
|
+
valid.
|
|
199
|
+
|
|
200
|
+
Keep stored content formats stable through persistence migration unless a change
|
|
201
|
+
is necessary. Evaluate replacement editors independently with real constructs,
|
|
202
|
+
round-trip conversion, diagnostics and the intended editor audience. Preserve
|
|
203
|
+
exact originals and distinguish semantic comparison rules from transformations
|
|
204
|
+
applied to stored data. Defer collaboration or other product work when outside
|
|
205
|
+
the agreed milestone.
|
|
@@ -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.
|