@gadicc/loom 1.27.0 → 1.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,400 @@
1
+ # Rollout and shared work
2
+
3
+ Use this reference to plan provider setup, production acceptance and retirement.
4
+ Its gates require evidence from the target app; they are not a ready-to-run
5
+ script.
6
+
7
+ Use [evidence and authority](#keep-evidence-and-authority-explicit) for provider
8
+ setup and release validation,
9
+ [backups](#back-up-every-authority-and-prove-recovery) for data recovery,
10
+ [cutover](#cut-over-one-writer-with-a-post-write-recovery-plan) for writer
11
+ transitions and retirement, and
12
+ [shared Loom work](#extract-shared-loom-behavior-without-moving-other-apps) when
13
+ extracting reusable changes. Read only the provider-specific paragraphs that
14
+ match the app's deployment path.
15
+
16
+ ## Keep evidence and authority explicit
17
+
18
+ Use a concise ledger per unit: source/artifact identity, test environment,
19
+ verification, current activation and remaining gate. Separate installed source,
20
+ emitted build, local browser, synthetic database, read-only production
21
+ observation and live provider mutation. Mocked storage is not CORS acceptance;
22
+ public byte retrieval is not private-bucket proof; a provisioned database is not
23
+ a migrated app. Correct earlier hypotheses when stronger runtime evidence
24
+ arrives.
25
+
26
+ Trace static-checker findings against emitted imports and the actual command
27
+ environment before changing a consumer to satisfy a pattern. Type-only imports
28
+ do not create runtime edges, and a parameterized environment-file wrapper may
29
+ correctly pass credentials to its child process. Confirm false positives with
30
+ concrete evidence, record the limitation, and fix shared analysis rather than
31
+ duplicating an unnecessary workaround across apps.
32
+
33
+ When a provider mutation fails, preserve its request identity and useful
34
+ redacted status/error evidence. Distinguish local argument parsing,
35
+ authentication and transport failures from provider rejection before retrying.
36
+ For a CLI regression, reproduce the full command entrypoint with network
37
+ disabled; testing only its handler can miss argument parsing and middleware.
38
+ After an uncertain response, inspect the recorded resource identity before
39
+ another mutation.
40
+
41
+ Treat an internal error from a provider build-patching step such as `patchBuild`
42
+ as an uncertain operation, not an invitation to resubmit. Inspect the exact
43
+ deployment, build and artifact state and bind it back to the original request
44
+ before deciding whether a new attempt is safe. Preserve the failed attempt's
45
+ sanitized evidence rather than overwriting it with a retry.
46
+
47
+ Provider subprocesses should receive only their required environment and
48
+ explicit account/profile and endpoint configuration. Inherited CLI host
49
+ overrides, runtime injection options or unrelated application secrets can
50
+ undermine an otherwise correct argument list. Keep useful safe status/error
51
+ codes without retaining raw credential-bearing diagnostics; test the actual
52
+ command entrypoint as well as its imported functions.
53
+
54
+ Inspect live compute/database placement, runtime, production branch and release
55
+ workflow. Pair compute and database based on actual users and measured
56
+ boundaries; function-to-database hot-query latency is not end-user page latency.
57
+ Verify current provider regions and extension availability. Present the concrete
58
+ region/resource/ plan/environment proposal when operator confirmation is
59
+ required; preserve an already approved choice. Local schema wiring can proceed
60
+ before provisioning.
61
+
62
+ SQL credentials do not establish provider control-plane access. Check existing
63
+ authenticated CLI profiles before asking for a new API key; when supported,
64
+ interactive browser authentication may be enough. Verify the exact project,
65
+ branch and endpoint through that identity rather than assuming an integration
66
+ account or a successful login has the necessary scope. Keep credential values
67
+ out of transcripts and use explicit profiles in multi-account work.
68
+
69
+ Project API access does not establish that a token can execute the CLI's
70
+ complete release path. Before the final writer pause, smoke the actual pull,
71
+ build and staging sequence that release will use. If a scoped token fails,
72
+ identify the exact account/team call and permission instead of broadening it by
73
+ guesswork. A broader fallback requires explicit operator approval, a limited
74
+ lifetime and a protected release environment. Keep the prior release credential
75
+ usable until the new release succeeds and its runtime is verified.
76
+
77
+ Preview-scoped variables do not prove isolated databases. Check branch/resource
78
+ identity and readiness, auth callbacks/cookies, storage and external
79
+ integrations before a preview can touch private data. Build with deliberately
80
+ isolated service configuration; tools and eager imports can otherwise contact
81
+ production during verification. Follow Loom's authoritative environment-loading
82
+ and sensitive-env release workflow. Do not print or commit credentials, private
83
+ fixtures or raw backup/transcript data. Create and verify owner-only checkpoint
84
+ directories before provisioning rehearsal resources, so a local privacy
85
+ preflight fails before any provider work. For exposed credentials, establish
86
+ actual use/scope and the rotation or retirement plan. Removing them from code
87
+ does not revoke access; do not inherit another app's decision to defer
88
+ retirement.
89
+
90
+ Before rotating a provider API key, verify its current status, including
91
+ revocation, the acting identity expected by the application, and the privileges
92
+ required by the routes it calls. When the provider and existing behavior allow
93
+ it, prefer a replacement bound to that service identity over a key that can act
94
+ for every user. Run a bounded read-only provider check before installation, then
95
+ prove the installed value only through a new deployment's runtime acceptance.
96
+
97
+ Stage credential material separately from non-secret target, intent and result
98
+ receipts. A hidden-input helper must promote any warning that terminal echo
99
+ could not be disabled to a hard failure; continuing to a fallback prompt can
100
+ expose the credential. Never copy the staged value into metadata evidence.
101
+
102
+ Some integrations inject branch-specific credentials only during deployment;
103
+ ordinary environment pulls show base variables. Equal base destinations do not
104
+ prove a deployed preview uses production, and different base destinations do not
105
+ prove its effective connection. Verify saved branching/readiness controls and
106
+ the deployment's actual destination. Copy-on-write isolation can still copy
107
+ private parent data, so review ancestry and the permitted dataset separately.
108
+
109
+ After editing an existing integration connection, recheck secret visibility as
110
+ well as its deployment actions. A dashboard save can apply a Sensitive default
111
+ while the operator is changing branching. If that removes an external CI
112
+ credential source, retrieve the connection through an authorized provider
113
+ profile and install the protected migration secret before releasing. Do not
114
+ assume `vercel pull` or an environment runner populated by its output can
115
+ recover Sensitive values. Distinguish unit coverage of placeholder/secret
116
+ precedence from a successful build, artifact scan, migration and staged runtime
117
+ using those actual provider settings.
118
+
119
+ Check deployment-target flags against the installed CLI before submitting a
120
+ probe. Vercel's `--skip-domain` is a production staging option and rejects
121
+ Preview deployments; Preview may receive its own generated branch alias. Bind
122
+ cleanup to the exact owned deployment and its recorded aliases. Retain a useful
123
+ sanitized error classification when a command fails, and resolve provider state
124
+ before retrying an uncertain submission. A supported dry run can expose local
125
+ argument errors without creating another deployment.
126
+
127
+ A different database endpoint does not by itself prove different credentials.
128
+ Check the provider's branch inheritance rules: Neon child roles ordinarily
129
+ inherit parent passwords, while children of protected branches get new ones.
130
+ Credential isolation and excluding private parent data are separate checks; a
131
+ protected parent alone does not sanitize the copied rows. See Neon's current
132
+ [protected-branch behavior](https://neon.com/docs/guides/protected-branches).
133
+
134
+ If a native Neon integration always branches from the production root, consider
135
+ a separate Preview resource whose root contains only migrations and approved
136
+ synthetic fixtures, rather than another child of the Production root. Keep
137
+ Production connected to its original resource. If Preview children are reused,
138
+ bind reuse to the exact Git ref and prove same-ref reuse and different-ref
139
+ separation; project/environment identity alone is insufficient. Distinguish a
140
+ project connection's environment list from a resource-wide production-only
141
+ policy: the latter also prevents future nonproduction connections. Verify costs
142
+ and current provider support before provisioning, and review credential rotation
143
+ when earlier previews inherited production passwords. Test the replacement
144
+ branch's ancestry, effective runtime identity and cleanup before private import.
145
+
146
+ ## Back up every authority and prove recovery
147
+
148
+ Record backup scope, time/consistency properties, fingerprints, counts and
149
+ indexes. A live logical dump without coordination is not a point-in-time cutover
150
+ snapshot. Restore into a disposable instance whose identity is checked before
151
+ use, verify counts/indexes/validation and stop/remove only owned resources
152
+ afterward. Include independent object bodies, vector stores and external
153
+ forums/services when the product relies on them. A copied archive's filesystem
154
+ date may differ from the data snapshot date. Include newly introduced
155
+ operation-receipt collections in later backups and inventories.
156
+
157
+ Rehearse exact migrations/importer against a disposable target using protected
158
+ real input where authorized. Persist stable aliases, checkpoints and every
159
+ source disposition. Compare references, natural keys, source hashes,
160
+ permissions, typed values and selected output—not only counts. Interrupt/resume
161
+ and rerun unchanged input; refuse newer target writes unless reconciliation is
162
+ defined. Disable unrelated mail, sign-in, vectors and integration writes during
163
+ rehearsal.
164
+
165
+ Persist reviewed allocations before starting database mutations. Publish local
166
+ checkpoints exclusively in a private durable directory, and preserve the final
167
+ file if an acknowledgement or directory sync fails after publication. Rehearse
168
+ the actual maintenance entrypoint in new processes with its source input absent;
169
+ matching service-level tests alone do not prove the launcher reuses saved IDs.
170
+ Bind a separately reviewed source/configuration/catalog/target artifact to the
171
+ command, and state which environment or cutover checks remain external to it.
172
+ Keep acknowledged receipts if later connection cleanup fails.
173
+
174
+ Make a resumable migration's artifact set closed. Its manifest should enumerate
175
+ every required source, fixture and configuration input, while a continuation
176
+ binds the reviewed target and earlier receipts by digest. Before resuming,
177
+ reject missing, extra or changed artifacts and changed executable logic; rebuild
178
+ the operation from the validated receipts instead of accepting a second
179
+ caller-supplied plan as authority. Keep the continuation small enough to review
180
+ without copying private payloads into it.
181
+
182
+ Exercise the actual application against the rehearsed target: existing
183
+ identities, roles, old URLs, legacy receipt recovery, conflicts, offline cold
184
+ start, account switches, uploads and integration mapping. Measure duration to
185
+ make an approved write pause achievable. An isolated SQL unit passing
186
+ constraints does not replace these journeys.
187
+
188
+ After a mutation ends in a UI error, inspect its persisted state and receipt
189
+ before retrying: redirect or render failure can follow a committed
190
+ domain-and-grant transaction. Use a proportionate read-only QA query for that
191
+ check; routine state inspection should not inherit full write-migration
192
+ machinery.
193
+
194
+ ## Cut over one writer with a post-write recovery plan
195
+
196
+ Before activation, ship or otherwise establish old-client recovery and protocol
197
+ fences, verified preview isolation, protected migration credentials,
198
+ migration-first deployment fencing and the required runtime/provider
199
+ configuration. Use the actual production branch; do not assume `main`. Review
200
+ the concrete release artifact and target before any externally visible switch
201
+ not already authorized.
202
+
203
+ For a pause-based cutover, stop/fence all writers and relevant jobs, take the
204
+ final consistent snapshot/delta, audit/import/compare it, verify the staged
205
+ application, then switch and reopen writes. If uninterrupted writes are
206
+ required, design and rehearse change capture/reconciliation explicitly; casual
207
+ dual-writing is not a substitute. Exactly one authority owns each operation at
208
+ every stage.
209
+
210
+ Before the new store accepts writes, recovery may return traffic to the
211
+ unchanged old authority. Afterwards, reverting code or restoring an old dump
212
+ alone loses acknowledged work. Recover to a compatible app on the new store, or
213
+ pause and use a rehearsed reverse-transfer/replay process. Keep receipts and
214
+ source mappings until all accepted work is reconciled. Do not remove browser
215
+ recovery merely because a calendar window elapsed; returning devices may hold
216
+ unique work.
217
+
218
+ Stop the switch for unexplained source/data/permission differences or failed
219
+ recovery. Report remaining blockers precisely while completing independent work.
220
+
221
+ A deployment CLI timeout may leave an alias change running at the provider.
222
+ Inspect actual promotion state and aliases, verify the intended artifact, and
223
+ refuse another release while an earlier operation remains unresolved. Recheck
224
+ after HTTP smoke tests: another promotion can start during those requests.
225
+ Workflow concurrency does not serialize manual provider changes.
226
+
227
+ Freeze every input covered by a migration rehearsal, including manifests and
228
+ lockfiles, across concurrent work. Verify both the reviewed copy and source tree
229
+ before and after each phase. If a guard stops the run, inspect the precise
230
+ failed check before attributing it to the provider. Preserve that run's
231
+ artifacts and use a fresh one-shot directory for a corrected rehearsal; never
232
+ overwrite its failure evidence. Keep source-free restart/retry checks in the
233
+ actual operator command path, rather than proving only a lower-level importer
234
+ helper.
235
+
236
+ Inspect the live credential's effective privileges and sharing before choosing a
237
+ writer fence. A database name in a connection string does not restrict an
238
+ account with cross-database write roles, and adding a read role does not
239
+ override broader write grants. Include auth callbacks, uploads, server actions,
240
+ jobs and historical deployment URLs. Changing the main domain alone cannot
241
+ retire old writers; drain in-flight work and preserve a fence after the
242
+ authority switch.
243
+
244
+ An operator's UI may make a cross-database read role the practical option. For a
245
+ dedicated legacy application principal, that can still be a write fence if the
246
+ verifier requires the exact sole role, inspects effective privileges, reads from
247
+ the primary with the intended consistency, and confirms a zero-match update with
248
+ `upsert: false` is rejected for authorization. Preserve the numeric code, code
249
+ name and a bounded semantic classification. Atlas can wrap an authorization
250
+ denial as code 8000 with `AtlasError`; code 8000 alone proves nothing, so
251
+ require the expected denial meaning and targeted operation without retaining raw
252
+ errors or credentials.
253
+
254
+ Validate a firewall draft by its intended effective policy as well as its change
255
+ records. A provider may omit an operation that merely restates a default, while
256
+ initializing a draft can also introduce provider defaults that were absent from
257
+ the proposal. If validation stops, preserve the attempt receipt and read back
258
+ the actual draft before recovery. Bind any recovery to that exact unchanged
259
+ state, remove only the reviewed unintended defaults, and verify the live
260
+ effective policy after activation.
261
+
262
+ Probe retained deployment URLs as well as the main domain. A provider can
263
+ normalize a path before its firewall runs. Inspect a redirect's exact target and
264
+ method semantics before classifying it as a bypass; for an observed same-origin,
265
+ method-preserving normalization, manually repeat the bodyless request at the
266
+ canonical path and require the write denial there. Keep automatic redirects off
267
+ and never forward a protection credential to another origin.
268
+
269
+ When protected staged checks need an automation identity, prefer supported
270
+ short-lived credentials with exact repository, immutable repository ID, branch,
271
+ workflow and environment constraints. Resolve renamed repositories before using
272
+ string claims. Configuring a trust exception is a separate provider security
273
+ change; establish authorization for its concrete scope. Verify the smoke target
274
+ through provider metadata before sending credentials, reject redirects and login
275
+ HTML, and check the public production alias without the bypass credential.
276
+
277
+ Deployment-management tokens and HTTP Deployment Protection identities are
278
+ different boundaries. A trust rule that admits a staged smoke request does not
279
+ authorize deployment API operations. Shared setup should preserve existing
280
+ write-only secrets on rerun, refuse rebinding them to another project, and make
281
+ rotation explicit. Record non-secret token identity and verified expiry for
282
+ later retirement. If secret installation has an uncertain acknowledgement, do
283
+ not revoke the replacement automatically: the receiving service may already be
284
+ using it. Preserve existing reviewers and branch policies when configuring
285
+ release access.
286
+
287
+ For persistent provider trust changes, bind a reviewable proposal to the exact
288
+ provider account and resource as well as repository, immutable repository ID,
289
+ workflow, branch and environment. The approved digest must cover that full
290
+ target, expected prior state and proposed patch. Hashing only a policy body can
291
+ let the same approval be redirected to another resource with identical settings.
292
+ Test that case explicitly. Recheck the existing policy immediately before
293
+ applying and verify the returned state. Preserve unrelated rules. A provider
294
+ without conditional updates still has a concurrent-change window; do not
295
+ describe a read/check/PATCH sequence as atomic.
296
+
297
+ Do not assume an environment argument subtracts one scope from a shared provider
298
+ record. Inspect the installed CLI or documented API semantics: a command may
299
+ filter by environment and then delete the whole matched record. To preserve
300
+ other environments, update shared records by exact identity with the retained
301
+ scopes. For an unreadable Sensitive record, use a scope-only patch that
302
+ preserves the provider-held value and type rather than sending a placeholder.
303
+ Delete by exact identity only when the record is already exclusive to the
304
+ retired environment. Read back every affected identity and scope before
305
+ proceeding.
306
+
307
+ Trace canonical settings, deprecated secret fallbacks and adapter selectors
308
+ together before retiring configuration. Exercise the runtime with old settings
309
+ absent and update build-environment requirements. An optional legacy adapter
310
+ should initialize only when a request actually needs it; absent-row or disabled
311
+ paths should retain their intended response without requiring retired secrets.
312
+
313
+ Distinguish fresh backend reads from CDN hits when verifying retirement. An
314
+ unchanged public response can prove byte parity while saying nothing about the
315
+ current storage credential. Reuse earlier exact-build evidence where valid and
316
+ combine it with a bounded direct read using the replacement credential when
317
+ caching prevents another runtime observation. Record those evidence boundaries;
318
+ do not silently weaken a check or purge production caches merely to satisfy it.
319
+
320
+ When one record spans Production and other environments, a safe rotation may
321
+ first narrow that record to the unaffected environments and then create a new
322
+ Production-only Sensitive record. Journal the intent before the first write and
323
+ treat a failure between those operations as a partial result requiring readback,
324
+ not a reason to repeat both writes blindly. Existing immutable deployments
325
+ retain their captured configuration; metadata success changes only later
326
+ deployments.
327
+
328
+ Sensitive configuration metadata can prove names, scopes and protection, but it
329
+ cannot prove hidden values are nonempty, current or accepted by the runtime.
330
+ Bind an inert deployment to the exact resource, verify only non-secret runtime
331
+ identity such as host/database hashes, test data and authentication separately
332
+ through a read-only path, and remove the exact disposable deployment and
333
+ provider children. A route that only parses configuration proves injection, not
334
+ database login, and a successful build proves neither. Production or Preview
335
+ labels do not strengthen that evidence. Require staged runtime proof for the
336
+ actual backend identity and each acceptance boundary the release claims.
337
+
338
+ A staged environment may intentionally omit model, search or other provider
339
+ configuration. Check the declared environment contract and current key metadata
340
+ before treating a configuration failure as an SDK defect. For a live model
341
+ smoke, check that the task's existing authorization covers the provider,
342
+ destination and data categories, including retrieved corpus; ask only for
343
+ missing scope or an explicit approval gate. Reject redirects, bound the
344
+ response, decode the real stream protocol and require its terminal completion
345
+ markers as well as a nonempty result. Preserve a sanitized failure receipt so an
346
+ uncertain request is not repeated blindly.
347
+
348
+ If staged acceptance requires temporarily relaxing deployment protection, state
349
+ the provider setting's full scope, including historical deployment URLs it also
350
+ protects. Record the exact original field and mutation intent before the
351
+ request. Restoration must bind to the project and expected paused state, patch
352
+ only that field, and proceed despite alias or deployment drift while reporting
353
+ the drift. Keep each uncertain restore attempt immutable and allow a new attempt
354
+ to recover after a lost response; readback makes an already-restored state
355
+ idempotent, while an unexpected external protection value must fail closed.
356
+
357
+ An unavailable provider audit is evidence about observability, not evidence of
358
+ inactivity. Preserve the bounded authorization/not-found or capability result
359
+ without response contents and label the audit unavailable. If the cutover
360
+ proceeds using writer inventory, an ingress fence, a verified maximum invocation
361
+ drain and an operator stop instead, state that narrower proof and its blind
362
+ spot. Require an authorized export before the pause when provider-side
363
+ before/after comparison is a hard gate; it cannot be reconstructed afterwards.
364
+
365
+ When a release verifier cannot observe an operation record, check the provider's
366
+ request contract before weakening the gate. An API may omit promotion or
367
+ rollback details unless a specific projection is requested. Trace the installed
368
+ provider CLI and compare a bounded live response. Preserve checks for the exact
369
+ completed operation, deployment and stable aliases around runtime probes. If
370
+ promotion succeeded but CI's final check failed, record the failed run and a
371
+ separate verification of the live deployment; do not repeat the promotion or
372
+ report CI as successful.
373
+
374
+ ## Extract shared Loom behavior without moving other apps
375
+
376
+ Read the Loom checkout's instructions and registries before touching it. Compare
377
+ active reference apps and separate stable shared primitives, optional capability
378
+ and app policy. Use thin configured wrappers. A richer app should not force its
379
+ domain schema, access roles, expiry duration, renderer or upload scope on
380
+ others.
381
+
382
+ Keep shared API changes additive where possible and verify emitted npm
383
+ contracts, including client/server directives and browser-safe entry points.
384
+ Test the consumer with actual package output; source tests alone miss bundling
385
+ drift. Use Loom's managed local-development/sync workflow, then adopt the exact
386
+ published release through `loom dev published` and the app's package/lockfile
387
+ changes.
388
+
389
+ Shared package publication and app deployment are separate external actions;
390
+ authorization for one does not authorize the other or upgrade unrelated apps.
391
+ Before shipping a consumer, pass `loom check --production` and verify no local
392
+ Loom resolution remains. A normal development warning can be an intentional
393
+ temporary state while its production gate still blocks release.
394
+
395
+ When developing a reusable skill during a migration, keep its draft outside Loom
396
+ if the operator asks to wait. Update it from observed failures and completed
397
+ integration, label prospective guidance, and remove app-specific choices. At
398
+ completion, reconcile the lesson ledger, independently test realistic use,
399
+ validate the skill, and integrate it through Loom's current skill packaging
400
+ workflow.