@wildo-ai/framework-knowledge 1.1.13 → 1.1.14

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.
Files changed (57) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
  4. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
  5. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  6. package/dist/knowledge/manifest.json +3 -3
  7. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  8. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  9. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +11 -2
  10. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  11. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  12. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  13. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  14. package/dist/knowledge/references/example.config.navigation.full.md +14 -0
  15. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  16. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  17. package/dist/knowledge/references/platform.config.environment.deployment.md +60 -4
  18. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  19. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  20. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  21. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
  22. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  23. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  24. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  25. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  26. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  27. package/dist/knowledge/registries/framework-topics.json +1 -1
  28. package/dist/knowledge/registries/playbooks.json +1 -1
  29. package/dist/knowledge/registries/source-tags.json +1038 -1038
  30. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +5 -1
  31. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  32. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
  33. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +11 -2
  34. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  35. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  36. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  37. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  38. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  39. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
  40. package/dist/knowledge/skills/infra-environment-config/SKILL.md +10 -6
  41. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +60 -4
  42. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  43. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  44. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  45. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  46. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
  47. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  48. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  49. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  50. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  51. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  52. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  53. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  54. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  55. package/dist/knowledge/topic-index.json +110 -110
  56. package/dist/tsconfig.build.tsbuildinfo +1 -1
  57. package/package.json +4 -4
@@ -214,7 +214,11 @@ const backendModule: BackendDomainModule = {
214
214
  ],
215
215
  // A signed webhook from a client's system that creates a todo (#1596) — `POST /webhooks/app/todo-intake`;
216
216
  // and an email to an organization's address that creates one and answers on the thread (#1600, #1630).
217
- inboundHandlers: [todoIntakeInboundHandler, todoEmailIntakeHandler, todoEmailScreenedHandler, todoEmailScreeningHandler],
217
+ // and what Teams sends the application's bot or an organization's own bot (#2663) — `POST /webhooks/microsoft-teams-bot/messages`.
218
+ inboundHandlers: [todoIntakeInboundHandler, todoEmailIntakeHandler, todoEmailScreenedHandler, todoEmailScreeningHandler, teamsBotInboundHandler],
219
+ // An agent's answer to a Teams conversation goes back through the bot it was sent to; startup refuses the Teams
220
+ // messages handler without it.
221
+ chatReplyHandlers: [teamsChatReplyHandler],
218
222
  // NOT listed: `todoSmsStatusHandler` (`./inbound/todos.sms-status.inbound-channel-handler`, #3394), a member's todo
219
223
  // status by text. An SMS channel handler stops the backend at startup while the SMS channel does not receive, and
220
224
  // Your Application keeps the SMS capability off (no vendor account, 2026-10-02). Enabling SMS with a provider whose
@@ -49,16 +49,39 @@ state (it was submitted meanwhile, its budget is closed) names no field: there i
49
49
  offered. Put the state in the condition (`resource-status-lifecycle`); the engine's own refusal then speaks the
50
50
  operation's `unavailableWhen`.
51
51
 
52
+ ## A state the condition already refuses: what arrives, and which rows to write
53
+
54
+ The engine judges `enabledCondition` BEFORE the operation runs. For a condition that reads only the record's state,
55
+ a refusal is a 409 whose `customMessageReference` is `service_resource_operation_disabled`, with no code, and the
56
+ person reads the operation's `unavailableWhen`. A condition that reads the caller (its user, its ids) or the request
57
+ before the state answers 403 for that refusal instead.
58
+
59
+ What the operation's own re-check of that state can then meet depends on WHICH row it reads:
60
+
61
+ - **It reads the row again itself** (an `OVERRIDE_ALL` implementation that fetches the record): a row that moved after
62
+ the request was admitted reaches it, so its code arrives in that race. Declare both: the condition's row first,
63
+ because it is what normally arrives, saying the code arrives only for a row that moved; then the code's row, whose
64
+ `when` stays the sentence the person reads.
65
+ - **It checks the row it was handed** (a prefix or postfix hook on `utils.currentObject`): that is the row the
66
+ condition judged, so the check never sees a moved one. A row that moved is refused by the write's own admission
67
+ precondition, a 409 `version_conflict`. Declare the condition's row and a `version_conflict` row; the code's row may
68
+ stay as a defence, but no HTTP caller normally meets it.
69
+
70
+ A specification that documents only the code tells a client to branch on a code it will almost never receive.
71
+
52
72
  ## Worked example
53
73
 
54
74
  From a todo application: the codes of one operation, the refusal carrying one, and the specification rows that give
55
- each code its sentence.
75
+ each code its sentence. The todo's settled state is also the operation's `enabledCondition`, so the rows start with the
76
+ condition's refusal and the code covers the race.
56
77
 
57
78
 
58
79
  ## Usage Example
59
80
 
60
81
  ```typescript
61
82
  // The person reads the CODE's words (`errors_refusals.<code>.msg`); `reason` and the ids stay for the logs.
83
+ // The operation's `enabledCondition` refuses this state before the operation runs; this re-check is for a todo
84
+ // settled after the request was admitted, read here from the row the operation acts on.
62
85
  if (todo.status === Todos_Status.COMPLETED || todo.status === Todos_Status.CANCELLED) {
63
86
  throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
64
87
  customMessageReference: ErrorCustomMessageReference.RESOURCE_STATUS_TRANSITION_CONFLICT,
@@ -88,7 +111,11 @@ export enum Todos_AutoResolveRefusalCode {
88
111
  ## Usage Example
89
112
 
90
113
  ```typescript
114
+ // A state the operation's `enabledCondition` already refuses arrives as the ENGINE's refusal, before the operation
115
+ // runs: no code, the operation's `unavailableWhen` for words. Document it first, since it is what normally arrives.
116
+ { code: HttpResponseStatusCode.CONFLICT_409, when: 'The todo is already completed or cancelled: the engine refuses on the operation\'s condition before it runs. ALREADY_SETTLED arrives instead only when the todo was settled after this request was admitted.', customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED },
91
117
  // Each code a refusal carries, declared with the sentence the person reads: the labelling pipeline writes it.
118
+ // ALREADY_SETTLED is the operation's own re-check of that state, against a row that moved after admission.
92
119
  { code: HttpResponseStatusCode.CONFLICT_409, errorCode: Todos_AutoResolveRefusalCode.ALREADY_SETTLED, when: 'The todo is already completed or cancelled, so there is nothing left to resolve.' },
93
120
  { code: HttpResponseStatusCode.CONFLICT_409, errorCode: Todos_AutoResolveRefusalCode.ALREADY_RUNNING, when: 'An auto-resolve run for this todo is still open. Wait for it to finish, or answer the approval it is waiting on.' },
94
121
  { code: HttpResponseStatusCode.CONFLICT_409, errorCode: Todos_AutoResolveRefusalCode.NOBODY_TO_TELL, when: 'The todo records no creator and the request did not come from a person, so nobody could be told how the run ended. Start it from a person\'s account.' },
@@ -47,6 +47,15 @@ short: declare `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_
47
47
  more by construction (one row by a unique key, a page it bounds itself), and say why. Without it the write stays best
48
48
  effort. A multi-row write with no custom implementation needs nothing: the framework runs it 100 rows per transaction.
49
49
 
50
+ `DELEGATES_WRITES_TO_AUDITED_OPERATIONS` is the posture of a purge whose handler writes nothing itself: it removes a
51
+ population nothing bounds (every row of a scope, every row past a cutoff) a page of at most 100 rows at a time, each
52
+ page through the resource's own declared `deleteMany` with no custom implementation, so each page is its own transaction
53
+ with its own audit row. The framework then never opens a transaction around the handler, and the operation's own audit
54
+ row is a summary written after the pages, best effort. It is accepted only on a REPLACE handler of a multi-row verb
55
+ (`deleteMany`, `updateMany`, or a custom operation borrowing one) without `transactionalCore`. The engine's SIEM
56
+ dead-letter `purgeAll` and webhook delivery-log `purgeOld` are written this way, with an engine-internal page walker that
57
+ applications do not receive; an application purge that wants the same guarantee must page through operations it declares.
58
+
50
59
  ## Import Origins
51
60
 
52
61
  - `@wildo-ai/saas-backend-lib`
@@ -80,11 +89,22 @@ effort. A multi-row write with no custom implementation needs nothing: the frame
80
89
  * provider call, or on an audit row that has to exist before the operation answers), so the write stays best effort,
81
90
  * reported under its own reason rather than as unreviewed. Say why at the declaration.
82
91
  *
83
- * A registration with `transactionalCore: true` already runs its hooks in a transaction and needs neither. Refused beside an
92
+ * DELEGATES_WRITES_TO_AUDITED_OPERATIONS records a third review (#2297): the hooks write nothing themselves. They select a
93
+ * population that nothing bounds (a purge of a whole scope, of every row past a cutoff) and remove it in pages of at most
94
+ * 100 rows, each through a declared operation of the resource (its hook-less internal `DELETE_MANY`), which the framework
95
+ * runs in its own transaction with its own audit row. So every row the operation removes is recorded through a crash, and
96
+ * the answer stays "everything was purged". The operation runs outside any framework transaction (inside one, the
97
+ * delegated writes would join it, unbounded), and its own row is a summary of those writes, written after them, best
98
+ * effort. Accepted only on a REPLACE handler without `transactionalCore`, and honoured only on a multi-row verb
99
+ * (`DELETE_MANY`, `UPDATE_MANY`, or a custom operation borrowing one); elsewhere the write is reported as unreviewed. The
100
+ * engine's purges walk their pages with an engine-internal helper that applications do not receive.
101
+ *
102
+ * A registration with `transactionalCore: true` already runs its hooks in a transaction and needs none of these. Refused beside an
84
103
  * `overrideAll` handler, which replaces the pipeline whose transaction this is about.
85
104
  */
86
105
  export enum ResourceCustomServiceImplementationHookTransactionPosture {
87
106
  RUNS_INSIDE_TRANSACTION = 'runs_inside_transaction',
88
107
  STAYS_OUTSIDE_TRANSACTION = 'stays_outside_transaction',
108
+ DELEGATES_WRITES_TO_AUDITED_OPERATIONS = 'delegates_writes_to_audited_operations',
89
109
  }
90
110
  ```
@@ -606,8 +606,17 @@ region, the places that region processes in, and a `status` (`inside`, `outside`
606
606
  `no-established-profile`). State the territories from this value, never from prose. `null` means no
607
607
  residency is declared: say the service makes no residency commitment rather than naming a region.
608
608
  `providers: null` means the providers' profiles were not read, so state the commitment without claiming
609
- every vendor keeps it. A configuration with any status other than `inside` is refused by `wildo config
610
- sync`, so a landed application normally shows only `inside`.
609
+ every vendor keeps it. A configuration with any status other than `inside` or `inside-at-rest` is
610
+ refused by `wildo config sync`, so a landed application normally shows only those two.
611
+
612
+ `storedAtRestTerritories` is a second, weaker promise the operator may opt into: a vendor whose region
613
+ keeps the data in those places and processes it elsewhere. Such a vendor has status `inside-at-rest` and
614
+ carries `storageTerritories`. Name it and say exactly that: the data is stored in those places, and it is
615
+ processed elsewhere. Never write that it processes inside the residency, and never fold it into a sentence
616
+ about the vendors that do. `storedAtRestTerritories: null` means the operator made no such promise.
617
+ When the entry carries a `storageCondition`, the storage holds only on that account arrangement (an add-on, a
618
+ plan, a subuser, data created after residency was set up): state it beside the places, in the vendor's terms,
619
+ so the reader sees what the promise rests on.
611
620
 
612
621
  **Completeness** — do not round any state up.
613
622
 
@@ -20,6 +20,12 @@ entity, a sub-processor list, a data processing agreement), each shows the page
20
20
  read. Open that page, check the fact still holds for YOUR arrangement, and only then write it into
21
21
  your entry. The commit is what adopts it; the suggestion is never your answer.
22
22
 
23
+ When the application relies on a vendor on its at-rest residency (`dataResidency.storedAtRestTerritories`), the
24
+ vendor processes in one place and stores in another. Say both: `processingRegions` where it processes, and
25
+ `storedAtRestIn` where it keeps the data at rest, in your words. The brief suggests the places from the vendor's
26
+ storage map, with the account arrangement they hold on (an add-on, a plan); check that arrangement is yours before
27
+ you write them. Until you do, the international-transfers fact names the vendor in `registerStatesNoStorageFor`.
28
+
23
29
  Date the register. `verification: { verifiedAt: 'YYYY-MM-DD', reverificationIntervalDays: N }` records
24
30
  when you last checked every entry against the vendors' pages, and how long that check stands (your own
25
31
  policy; a yearly supplier review is common). The staleness report (`complianceFactStaleness`) then names
@@ -297,6 +303,16 @@ const ProcessorIdentityFieldsSchema = z.object({
297
303
  * `Ireland`, `United States`), and a fixed list would be wrong for the next vendor.
298
304
  */
299
305
  processingRegions: z.array(z.string().trim().min(1)).min(1),
306
+ /**
307
+ * Where this processor keeps the data AT REST, when that differs from where it processes it (#3921): a vendor admitted
308
+ * on the application's opt-in at-rest residency stores in one place and processes in another, and a register that
309
+ * named only the processing region could not say the half a reader of the weaker promise needs.
310
+ *
311
+ * In the operator's words, like {@link processingRegions}. The framework SUGGESTS it from the vendor profile's storage
312
+ * map for the chosen region, and the operator adopts it by committing it here, like every other vendor fact (#1744).
313
+ * Absent means not stated; the international-transfers fact names every `inside-at-rest` provider whose entry lacks it.
314
+ */
315
+ storedAtRestIn: z.array(z.string().trim().min(1)).min(1).optional(),
300
316
  /**
301
317
  * The processor's own subprocessors.
302
318
  *
@@ -93,20 +93,35 @@ places and whether it is inside.
93
93
  *
94
94
  * Opt-in. Absent means the application states no residency and nothing is refused, which is not the same as "anywhere":
95
95
  * the documents then say no residency is declared.
96
+ *
97
+ * ## A second, weaker promise: stored at rest (`storedAtRestTerritories`, #2294, decided by Paul 2026-11-15)
98
+ *
99
+ * Most SaaS vendors' "data residency" keeps data AT REST in a region while processing it elsewhere (Notion, Slack,
100
+ * Atlassian, Sentry…), so `territories` refuses them. `storedAtRestTerritories` admits such a vendor when every place its
101
+ * chosen region keeps data at rest (`storageRegionTerritories` on its profile) lies inside it. It is a separate field and
102
+ * never a looser reading of `territories`: a storage-only vendor is never INSIDE the processing residency, its entry says
103
+ * `inside-at-rest`, and the documents state that weaker promise for it by name. Opt-in: absent, nothing changes.
96
104
  */
97
105
  export const ApplicationDataResidencySchema = z
98
106
  .strictObject({
99
107
  /** The places the data may be stored and processed in. A vendor region counts as inside when every place it covers is inside one of these. */
100
- territories: z.array(JurisdictionSlugSchema).min(1),
108
+ territories: z.array(JurisdictionSlugSchema).min(1)
109
+ .describe('The places the data may be stored and processed in, as jurisdiction slugs (`eu`, `de`, `ch`, `us`; the EEA is `eu`, `is`, `li` and `no`). A vendor region counts as inside when every place it covers is inside one of these.'),
110
+ /** The places a vendor may keep the data AT REST in while processing it elsewhere (opt-in, the weaker promise). */
111
+ storedAtRestTerritories: z.array(JurisdictionSlugSchema).min(1).optional()
112
+ .describe('Opt-in, the weaker promise: the places a vendor that processes elsewhere may keep the data at rest in. A vendor whose chosen region processes outside `territories` is admitted when every place that region stores data at rest lies inside one of these, and the documents say so for it. Absent: no vendor is admitted on storage alone.'),
101
113
  })
102
114
  .superRefine((residency, context) => {
103
- const duplicates = residency.territories.filter((territory, index) => residency.territories.indexOf(territory) !== index);
104
- if (duplicates.length > 0) {
105
- context.addIssue({
106
- code: 'custom',
107
- path: ['territories'],
108
- message: `data residency territory ${[...new Set(duplicates)].map((slug) => `"${slug}"`).join(', ')} is declared more than once`,
109
- });
115
+ for (const field of ['territories', 'storedAtRestTerritories'] as const) {
116
+ const listed = residency[field] ?? [];
117
+ const duplicates = listed.filter((territory, index) => listed.indexOf(territory) !== index);
118
+ if (duplicates.length > 0) {
119
+ context.addIssue({
120
+ code: 'custom',
121
+ path: [field],
122
+ message: `data residency territory ${[...new Set(duplicates)].map((slug) => `"${slug}"`).join(', ')} is declared more than once`,
123
+ });
124
+ }
110
125
  }
111
126
  });
112
127
  export type ApplicationDataResidency = z.infer<typeof ApplicationDataResidencySchema>;
@@ -148,8 +163,20 @@ export function organizationDataResidencyRefusal(
148
163
  + 'narrow: nothing has placed its providers in named places. Declare the application\'s residency first.';
149
164
  }
150
165
  const outside = organization.territories.filter((territory) => !application.territories.some((resident) => jurisdictionReachCovers(resident, territory)));
151
- if (outside.length === 0) return null;
152
- return `The organization's data residency names ${outside.join(', ')}, outside the application's (${application.territories.join(', ')}). `
166
+ if (outside.length > 0) {
167
+ return `The organization's data residency names ${outside.join(', ')}, outside the application's (${application.territories.join(', ')}). `
168
+ + 'An organization can only narrow the application\'s residency: name places inside it.';
169
+ }
170
+ // The weaker promise narrows the same way, and only where the application made it (#2294).
171
+ if (organization.storedAtRestTerritories === undefined) return null;
172
+ if (application.storedAtRestTerritories === undefined) {
173
+ return 'The organization admits vendors on storage at rest (storedAtRestTerritories), and the application does not: an organization '
174
+ + 'can only narrow the application\'s residency. Remove storedAtRestTerritories, or declare it on the application first.';
175
+ }
176
+ const appStored = application.storedAtRestTerritories;
177
+ const storedOutside = organization.storedAtRestTerritories.filter((territory) => !appStored.some((resident) => jurisdictionReachCovers(resident, territory)));
178
+ if (storedOutside.length === 0) return null;
179
+ return `The organization's at-rest residency names ${storedOutside.join(', ')}, outside the application's (${appStored.join(', ')}). `
153
180
  + 'An organization can only narrow the application\'s residency: name places inside it.';
154
181
  }
155
182
 
@@ -203,6 +230,40 @@ export function effectiveDataResidencyTerritories(
203
230
  }
204
231
  return [...kept].sort((left, right) => left.localeCompare(right));
205
232
  }
233
+
234
+ /**
235
+ * The residency a call for an organization must satisfy, both promises narrowed (#2294): the processing territories as
236
+ * {@link effectiveDataResidencyTerritories} computes them, and the at-rest ones the same way when BOTH residencies make
237
+ * that promise. An organization that does not admit storage-only vendors narrows the application's admission away; an
238
+ * application that does not, has nothing for an organization to narrow. `undefined` when the organization declares none.
239
+ */
240
+ export function effectiveDataResidency(
241
+ application: ApplicationDataResidency | undefined,
242
+ organization: OrganizationDataResidency | null | undefined,
243
+ ): ApplicationDataResidency | undefined {
244
+ const territories = effectiveDataResidencyTerritories(application, organization);
245
+ if (territories === undefined) return undefined;
246
+ const storedAtRestTerritories = organization?.storedAtRestTerritories === undefined
247
+ ? undefined
248
+ : application === undefined
249
+ ? [...organization.storedAtRestTerritories]
250
+ : application.storedAtRestTerritories === undefined
251
+ ? undefined
252
+ : narrowedTerritories(application.storedAtRestTerritories, organization.storedAtRestTerritories);
253
+ return { territories: [...territories], ...(storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories }) };
254
+ }
255
+
256
+ /** Every place both lists contain, as the narrower of each pair; sorted. */
257
+ function narrowedTerritories(wider: readonly string[], narrower: readonly string[]): string[] {
258
+ const kept = new Set<string>();
259
+ for (const territory of narrower) {
260
+ for (const resident of wider) {
261
+ if (jurisdictionReachCovers(resident, territory)) kept.add(territory);
262
+ else if (jurisdictionReachCovers(territory, resident)) kept.add(resident);
263
+ }
264
+ }
265
+ return [...kept].sort((left, right) => left.localeCompare(right));
266
+ }
206
267
  ```
207
268
 
208
269
  ### Origin Package: `@wildo-ai/saas-models`
@@ -215,6 +276,12 @@ export function effectiveDataResidencyTerritories(
215
276
  export enum ProviderDataResidencyStatus {
216
277
  /** Every place the chosen region processes in lies inside the residency. */
217
278
  INSIDE = 'inside',
279
+ /**
280
+ * The weaker promise (`storedAtRestTerritories`, opt-in): the chosen region processes outside the residency, or nothing
281
+ * says where it processes, and every place it keeps data AT REST lies inside the at-rest territories. Admitted, and
282
+ * never INSIDE: the documents say the vendor stores the data in the region and processes it elsewhere.
283
+ */
284
+ INSIDE_AT_REST = 'inside-at-rest',
218
285
  /** The chosen region processes in at least one place outside the residency. */
219
286
  OUTSIDE = 'outside',
220
287
  /** The profile does not state which places the chosen region covers (a global region, or a map not yet researched). */
@@ -286,9 +353,30 @@ export interface ProviderDataResidencyEntry {
286
353
  readonly territories: readonly string[] | null;
287
354
  /** The places outside the residency, for {@link ProviderDataResidencyStatus.OUTSIDE}; empty otherwise. */
288
355
  readonly outsideTerritories: readonly string[];
356
+ /** The places the region keeps data at rest in, for {@link ProviderDataResidencyStatus.INSIDE_AT_REST}; `null` otherwise. */
357
+ readonly storageTerritories?: readonly string[] | null;
358
+ /**
359
+ * The account condition {@link storageTerritories} holds on (#3920), for {@link ProviderDataResidencyStatus.INSIDE_AT_REST}:
360
+ * what the operator attested by choosing the region. `null` when the map holds on the choice alone.
361
+ */
362
+ readonly storageCondition?: string | null;
289
363
  readonly status: ProviderDataResidencyStatus;
290
364
  }
291
365
 
366
+ /**
367
+ * Whether a provider at this status may be used under the residency (#2294): INSIDE, or INSIDE_AT_REST, the weaker promise
368
+ * the application opted into. Every admission site reads this, so a status added later is refused until it is placed here.
369
+ *
370
+ * A type guard, so a caller that returns early on an admitted status keeps an exhaustive switch over the rest (the
371
+ * placement below does): a plain boolean would leave INSIDE and INSIDE_AT_REST in the switch's type, which a strict
372
+ * program reports as a missing return.
373
+ */
374
+ export function providerDataResidencyAdmits(
375
+ status: ProviderDataResidencyStatus,
376
+ ): status is ProviderDataResidencyStatus.INSIDE | ProviderDataResidencyStatus.INSIDE_AT_REST {
377
+ return status === ProviderDataResidencyStatus.INSIDE || status === ProviderDataResidencyStatus.INSIDE_AT_REST;
378
+ }
379
+
292
380
  /** What the residency reads of a provider choice: who runs it, and in which region. */
293
381
  export type ProviderDataResidencyChoice = Pick<ApplicationProviderComplianceChoice, 'deploymentModel' | 'processingRegion'>;
294
382
 
@@ -358,6 +446,8 @@ function providerDataResidencyEntryOf(input: {
358
446
  processingRegion: choice.processingRegion,
359
447
  profileEstablished: established !== null,
360
448
  regionTerritories: established?.processingRegionTerritories?.[choice.processingRegion] ?? null,
449
+ regionStorageTerritories: established?.storageRegionTerritories?.[choice.processingRegion] ?? null,
450
+ regionStorageCondition: established?.storageRegionConditions?.[choice.processingRegion] ?? null,
361
451
  residency,
362
452
  });
363
453
  }
@@ -368,21 +458,37 @@ function vendorRegionDataResidencyEntry(input: {
368
458
  readonly processingRegion: string;
369
459
  readonly profileEstablished: boolean;
370
460
  readonly regionTerritories: readonly string[] | null;
461
+ readonly regionStorageTerritories: readonly string[] | null;
462
+ readonly regionStorageCondition: string | null;
371
463
  readonly residency: ApplicationDataResidency;
372
464
  }): ProviderDataResidencyEntry {
373
465
  const base = { providerRef: input.providerRef, processingRegion: input.processingRegion };
374
466
  if (!input.profileEstablished) {
375
467
  return { ...base, territories: null, outsideTerritories: [], status: ProviderDataResidencyStatus.NO_ESTABLISHED_PROFILE };
376
468
  }
377
- if (input.regionTerritories === null) {
378
- return { ...base, territories: null, outsideTerritories: [], status: ProviderDataResidencyStatus.TERRITORY_UNKNOWN };
379
- }
380
- const outsideTerritories = territoriesOutsideDataResidency(input.regionTerritories, input.residency);
469
+ const processing: ProviderDataResidencyEntry = input.regionTerritories === null
470
+ ? { ...base, territories: null, outsideTerritories: [], status: ProviderDataResidencyStatus.TERRITORY_UNKNOWN }
471
+ : (() => {
472
+ const outsideTerritories = territoriesOutsideDataResidency(input.regionTerritories, input.residency);
473
+ return {
474
+ ...base,
475
+ territories: [...input.regionTerritories],
476
+ outsideTerritories,
477
+ status: outsideTerritories.length === 0 ? ProviderDataResidencyStatus.INSIDE : ProviderDataResidencyStatus.OUTSIDE,
478
+ };
479
+ })();
480
+ // The processing promise first, always: a region inside it is INSIDE whatever it stores. The weaker one is asked only
481
+ // of a region the processing promise refuses, and only when the application opted into it (#2294).
482
+ if (processing.status === ProviderDataResidencyStatus.INSIDE) return processing;
483
+ const atRest = input.residency.storedAtRestTerritories;
484
+ if (atRest === undefined || input.regionStorageTerritories === null) return processing;
485
+ const storedOutside = input.regionStorageTerritories.filter((territory) => !atRest.some((resident) => jurisdictionReachCovers(resident, territory)));
486
+ if (storedOutside.length > 0) return processing;
381
487
  return {
382
- ...base,
383
- territories: [...input.regionTerritories],
384
- outsideTerritories,
385
- status: outsideTerritories.length === 0 ? ProviderDataResidencyStatus.INSIDE : ProviderDataResidencyStatus.OUTSIDE,
488
+ ...processing,
489
+ storageTerritories: [...input.regionStorageTerritories],
490
+ storageCondition: input.regionStorageCondition,
491
+ status: ProviderDataResidencyStatus.INSIDE_AT_REST,
386
492
  };
387
493
  }
388
494
 
@@ -403,6 +509,8 @@ export function dataResidencyEntriesOf(
403
509
  processingRegion: entry.choice.processingRegion!,
404
510
  profileEstablished: entry.offered !== null,
405
511
  regionTerritories: entry.regionTerritories,
512
+ regionStorageTerritories: entry.regionStorageTerritories,
513
+ regionStorageCondition: entry.regionStorageCondition,
406
514
  residency,
407
515
  }));
408
516
  }
@@ -448,6 +556,13 @@ export interface ProviderDataResidencyPlacement {
448
556
  readonly outcome: ProviderDataResidencyPlacementOutcome;
449
557
  /** The provider's vendor regions whose stated places all lie inside the residency, in the profile's order. */
450
558
  readonly regionsInside: readonly string[];
559
+ /**
560
+ * The vendor regions admitted only on the weaker promise (#3876): every place the region keeps data at rest lies inside
561
+ * the residency's `storedAtRestTerritories`, while it processes elsewhere. Empty when the residency declares no at-rest
562
+ * list, and never a region already in {@link regionsInside}. Read only when no region processes inside: a placement
563
+ * offers the stronger promise first.
564
+ */
565
+ readonly regionsInsideAtRest: readonly string[];
451
566
  /** The choice to write, for {@link ProviderDataResidencyPlacementOutcome.DERIVED} only. */
452
567
  readonly derivedChoice?: { readonly deploymentModel: ProviderDeploymentModel.VENDOR_HOSTED; readonly processingRegion: string };
453
568
  }
@@ -462,10 +577,16 @@ export interface ProviderDataResidencyPlacement {
462
577
  * Derived only when the residency leaves no choice: the provider is only offered vendor-hosted, exactly one of its
463
578
  * regions processes wholly inside, and no authored choice names a region. Everything else is a decision, and is
464
579
  * returned with the regions that would satisfy the residency so whoever takes it sees the options.
580
+ *
581
+ * When the application also declares an at-rest residency (#3876), a provider with NO region processing inside is placed
582
+ * on the weaker promise instead: derived when exactly one of its regions keeps everything at rest inside
583
+ * `storedAtRestTerritories`, a choice when several do. A region that processes inside always wins, because it keeps the
584
+ * stronger promise; a placement never trades it for a storage-only one.
465
585
  */
466
586
  export function placeProvidersInsideDataResidency(params: Parameters<typeof assessProviderProcessingAgainstDataResidency>[0]): readonly ProviderDataResidencyPlacement[] {
467
587
  return assessProviderProcessingAgainstDataResidency(params).flatMap((assessment): ProviderDataResidencyPlacement[] => {
468
- if (assessment.status === ProviderDataResidencyStatus.INSIDE) return [];
588
+ // An admitted provider needs no placement; an INSIDE_AT_REST one is admitted on the weaker promise the application made.
589
+ if (providerDataResidencyAdmits(assessment.status)) return [];
469
590
  const profile = Object.hasOwn(params.profilesByProviderRef, assessment.providerRef) ? params.profilesByProviderRef[assessment.providerRef] : undefined;
470
591
  const established = establishedProviderComplianceProfile(profile);
471
592
  const regionsInside = established === null
@@ -474,8 +595,15 @@ export function placeProvidersInsideDataResidency(params: Parameters<typeof asse
474
595
  const territories = established.processingRegionTerritories?.[region];
475
596
  return territories !== undefined && territoriesOutsideDataResidency(territories, params.residency).length === 0;
476
597
  });
598
+ const atRest = params.residency.storedAtRestTerritories;
599
+ const regionsInsideAtRest = established === null || atRest === undefined
600
+ ? []
601
+ : established.processingRegions.filter((region) => {
602
+ const stored = established.storageRegionTerritories?.[region];
603
+ return !regionsInside.includes(region) && stored !== undefined && territoriesOutsideDataResidency(stored, { territories: atRest }).length === 0;
604
+ });
477
605
  const placement = (outcome: ProviderDataResidencyPlacementOutcome): ProviderDataResidencyPlacement[] => [
478
- { providerRef: assessment.providerRef, assessment, outcome, regionsInside },
606
+ { providerRef: assessment.providerRef, assessment, outcome, regionsInside, regionsInsideAtRest },
479
607
  ];
480
608
  switch (assessment.status) {
481
609
  case ProviderDataResidencyStatus.NO_ESTABLISHED_PROFILE:
@@ -494,14 +622,17 @@ export function placeProvidersInsideDataResidency(params: Parameters<typeof asse
494
622
  if (assessment.status === ProviderDataResidencyStatus.NO_CHOICE && established.deploymentModels.includes(ProviderDeploymentModel.SELF_HOSTED)) {
495
623
  return placement(ProviderDataResidencyPlacementOutcome.DEPLOYMENT_MODEL_IS_A_CHOICE);
496
624
  }
497
- if (regionsInside.length === 0) return placement(ProviderDataResidencyPlacementOutcome.NO_REGION_INSIDE);
498
- if (regionsInside.length > 1) return placement(ProviderDataResidencyPlacementOutcome.SEVERAL_REGIONS_INSIDE);
625
+ // The stronger promise first: a region processing inside is never traded for one that only stores inside.
626
+ const candidates = regionsInside.length > 0 ? regionsInside : regionsInsideAtRest;
627
+ if (candidates.length === 0) return placement(ProviderDataResidencyPlacementOutcome.NO_REGION_INSIDE);
628
+ if (candidates.length > 1) return placement(ProviderDataResidencyPlacementOutcome.SEVERAL_REGIONS_INSIDE);
499
629
  return [{
500
630
  providerRef: assessment.providerRef,
501
631
  assessment,
502
632
  outcome: ProviderDataResidencyPlacementOutcome.DERIVED,
503
633
  regionsInside,
504
- derivedChoice: { deploymentModel: ProviderDeploymentModel.VENDOR_HOSTED, processingRegion: regionsInside[0]! },
634
+ regionsInsideAtRest,
635
+ derivedChoice: { deploymentModel: ProviderDeploymentModel.VENDOR_HOSTED, processingRegion: candidates[0]! },
505
636
  }];
506
637
  }
507
638
  }
@@ -516,16 +647,25 @@ export function placeProvidersInsideDataResidency(params: Parameters<typeof asse
516
647
  */
517
648
  export function dataResidencyPlacementStatement(placement: ProviderDataResidencyPlacement, residency: ApplicationDataResidency): string {
518
649
  const declared = residency.territories.join(', ');
650
+ const atRest = residency.storedAtRestTerritories?.join(', ');
519
651
  const at = `providerComplianceChoices.${placement.providerRef}`;
520
- const inside = placement.regionsInside.map((region) => `"${region}"`).join(', ');
652
+ // The candidates a placement chose among: the regions processing inside, else (#3876) the ones storing inside at rest.
653
+ const onlyAtRest = placement.regionsInside.length === 0 && placement.regionsInsideAtRest.length > 0;
654
+ const inside = (onlyAtRest ? placement.regionsInsideAtRest : placement.regionsInside).map((region) => `"${region}"`).join(', ');
521
655
  switch (placement.outcome) {
522
656
  case ProviderDataResidencyPlacementOutcome.DERIVED:
523
- return `Provider "${placement.providerRef}" processes in region "${placement.derivedChoice?.processingRegion}", the only one of its regions inside the data residency (${declared}).`;
657
+ return onlyAtRest
658
+ ? `Provider "${placement.providerRef}" uses region "${placement.derivedChoice?.processingRegion}", the only one of its regions keeping data at rest inside the at-rest residency (${atRest}). `
659
+ + `It processes outside the data residency (${declared}), so it is admitted on the weaker promise and the documents say so.`
660
+ : `Provider "${placement.providerRef}" processes in region "${placement.derivedChoice?.processingRegion}", the only one of its regions inside the data residency (${declared}).`;
524
661
  case ProviderDataResidencyPlacementOutcome.SEVERAL_REGIONS_INSIDE:
525
- return `Provider "${placement.providerRef}" has several regions inside the data residency (${declared}): ${inside}. Choose one as ${at}.processingRegion (deploymentModel VENDOR_HOSTED).`;
662
+ return onlyAtRest
663
+ ? `Provider "${placement.providerRef}" has several regions keeping data at rest inside the at-rest residency (${atRest}), none processing inside the data residency (${declared}): ${inside}. Choose one as ${at}.processingRegion (deploymentModel VENDOR_HOSTED).`
664
+ : `Provider "${placement.providerRef}" has several regions inside the data residency (${declared}): ${inside}. Choose one as ${at}.processingRegion (deploymentModel VENDOR_HOSTED).`;
526
665
  case ProviderDataResidencyPlacementOutcome.NO_REGION_INSIDE:
527
- return `Provider "${placement.providerRef}" has no region its profile states to process wholly inside the data residency (${declared}). `
528
- + 'Replace it with a provider that does, run it self-hosted if it is offered that way, or widen the residency.';
666
+ return `Provider "${placement.providerRef}" has no region its profile states to process wholly inside the data residency (${declared})`
667
+ + (atRest === undefined ? '' : `, nor to keep data at rest wholly inside the at-rest residency (${atRest})`)
668
+ + '. Replace it with a provider that does, run it self-hosted if it is offered that way, or widen the residency.';
529
669
  case ProviderDataResidencyPlacementOutcome.DEPLOYMENT_MODEL_IS_A_CHOICE:
530
670
  return `Provider "${placement.providerRef}" can be run by its vendor or by you: decide which as ${at}.deploymentModel`
531
671
  + (placement.regionsInside.length === 0 ? ` (none of its vendor regions lies inside the data residency, ${declared}).` : ` (vendor regions inside the data residency, ${declared}: ${inside}).`);
@@ -559,6 +699,7 @@ export function dataResidencyRefusalOf(
559
699
  : `providerComplianceChoices.${entry.providerRef}.processingRegion "${entry.processingRegion}"`;
560
700
  switch (entry.status) {
561
701
  case ProviderDataResidencyStatus.INSIDE:
702
+ case ProviderDataResidencyStatus.INSIDE_AT_REST:
562
703
  return null;
563
704
  case ProviderDataResidencyStatus.OUTSIDE:
564
705
  return `${where} processes in ${entry.outsideTerritories.join(', ')}, outside the declared data residency (${declared}). `
@@ -602,13 +743,14 @@ export function dataResidencyRefusalOf(
602
743
  * places goes only to a processor whose chosen region processes inside them.
603
744
  */
604
745
  export function assessProviderCallAgainstDataResidency(params: {
605
- readonly territories: readonly string[];
746
+ /** The residency the call must satisfy: both promises, narrowed for the organization ({@link effectiveDataResidency}). */
747
+ readonly residency: ApplicationDataResidency;
606
748
  readonly providerRef: string;
607
749
  readonly choice: ProviderDataResidencyChoice | undefined;
608
750
  readonly profile: ProviderComplianceProfile | undefined;
609
751
  readonly account: ProviderCallAccount;
610
752
  }): ProviderDataResidencyEntry | null {
611
- const residency: ApplicationDataResidency = { territories: [...params.territories] as ApplicationDataResidency['territories'] };
753
+ const { residency } = params;
612
754
  if (params.account === ProviderCallAccount.OWNER) {
613
755
  const established = establishedProviderComplianceProfile(params.profile);
614
756
  if (established !== null && providerIsAlwaysSelfHosted(established)) return null;
@@ -667,6 +809,8 @@ export function dataResidencyRefusals(entries: readonly ProviderDataResidencyEnt
667
809
  */
668
810
  export const RuntimeProviderDataResidencySchema = z.strictObject({
669
811
  territories: z.array(JurisdictionSlugSchema).min(1),
812
+ /** The opt-in at-rest territories (#2294), carried only when the application declares them. */
813
+ storedAtRestTerritories: z.array(JurisdictionSlugSchema).min(1).optional(),
670
814
  choices: z.record(z.string().min(1), z.strictObject({
671
815
  deploymentModel: z.enum(ProviderDeploymentModel),
672
816
  processingRegion: z.string().min(1).optional(),
@@ -684,6 +828,7 @@ export function runtimeProviderDataResidencyFor(input: {
684
828
  const choices = input.choices ?? {};
685
829
  return {
686
830
  territories: [...input.residency.territories],
831
+ ...(input.residency.storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories: [...input.residency.storedAtRestTerritories] }),
687
832
  choices: Object.fromEntries([...new Set(input.providerRefs)].sort((left, right) => left.localeCompare(right))
688
833
  .filter((providerRef) => Object.hasOwn(choices, providerRef))
689
834
  .map((providerRef) => {
@@ -708,10 +853,22 @@ export function narrowRuntimeProviderDataResidency(
708
853
  if (runtime === undefined) return undefined;
709
854
  return {
710
855
  territories: [...runtime.territories],
856
+ ...(runtime.storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories: [...runtime.storedAtRestTerritories] }),
711
857
  choices: Object.fromEntries(Object.entries(runtime.choices).filter(([providerRef]) => providerRefs.includes(providerRef))),
712
858
  };
713
859
  }
714
860
 
861
+ /**
862
+ * The application's declared residency as a runtime artifact carries it, both promises (#2294). The one reading the
863
+ * loader's re-check and the per-organization gate share, so neither can drop the at-rest territories the other applies.
864
+ */
865
+ export function applicationDataResidencyOfRuntime(runtime: RuntimeProviderDataResidency): ApplicationDataResidency {
866
+ return {
867
+ territories: [...runtime.territories],
868
+ ...(runtime.storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories: [...runtime.storedAtRestTerritories] }),
869
+ };
870
+ }
871
+
715
872
  /**
716
873
  * The residency a runtime re-applies at load, over the providers it loaded: `providerRef` -> the refusal, for every one
717
874
  * that is not inside. The backend provider loader leaves each unresolved, so startup refuses naming it.
@@ -721,7 +878,7 @@ export function runtimeDataResidencyRefusalsByProvider(input: {
721
878
  readonly providerRefs: readonly string[];
722
879
  readonly profilesByProviderRef: Readonly<Record<string, ProviderComplianceProfile | undefined>>;
723
880
  }): ReadonlyMap<string, string> {
724
- const residency: ApplicationDataResidency = { territories: input.runtime.territories };
881
+ const residency = applicationDataResidencyOfRuntime(input.runtime);
725
882
  const refusals = new Map<string, string>();
726
883
  // Only the providers this host LOADED: a choice for one that failed to load for another reason must not replace that
727
884
  // reason, and a provider that is not loaded receives no call.
@@ -1048,6 +1205,13 @@ export interface ProviderComplianceChoiceAssessmentEntry {
1048
1205
  * region is chosen or the profile does not map it.
1049
1206
  */
1050
1207
  readonly regionTerritories: readonly string[] | null;
1208
+ /**
1209
+ * The places the chosen region keeps data at rest in, from the profile's `storageRegionTerritories` (#2294). `null` when
1210
+ * no region is chosen or the profile does not map its storage.
1211
+ */
1212
+ readonly regionStorageTerritories: readonly string[] | null;
1213
+ /** The condition the chosen region's storage map holds on, from `storageRegionConditions` (#3920); `null` when none. */
1214
+ readonly regionStorageCondition: string | null;
1051
1215
  }
1052
1216
 
1053
1217
  /** Assess ONE choice against the provider's profile. See {@link ProviderComplianceChoiceAssessment}. */
@@ -1091,6 +1255,8 @@ export function assessProviderComplianceChoices(params: {
1091
1255
  offered: established === null ? null : { deploymentModels: established.deploymentModels, processingRegions: established.processingRegions },
1092
1256
  regionReach: choice.processingRegion === undefined ? null : established?.processingRegionReach?.[choice.processingRegion]?.kind ?? null,
1093
1257
  regionTerritories: choice.processingRegion === undefined ? null : established?.processingRegionTerritories?.[choice.processingRegion] ?? null,
1258
+ regionStorageTerritories: choice.processingRegion === undefined ? null : established?.storageRegionTerritories?.[choice.processingRegion] ?? null,
1259
+ regionStorageCondition: choice.processingRegion === undefined ? null : established?.storageRegionConditions?.[choice.processingRegion] ?? null,
1094
1260
  };
1095
1261
  });
1096
1262
  }
@@ -337,6 +337,36 @@ export const SHELL_GHOST_LAYER_ATTRIBUTE = 'data-shell-ghost-layer';
337
337
  /** The attribute every ghost carries, with its kind (`ShellGhostKind`). */
338
338
  export const SHELL_GHOST_ATTRIBUTE = 'data-shell-ghost';
339
339
 
340
+ /**
341
+ * The markers a still picture of an engine element must NOT carry: everything a query for the real element, or for a
342
+ * control inside it, finds it by. A picture (a discarded pane leaving, an image behind an expanded pane, a pressed row
343
+ * flying into its pane) is inert and takes no pointer, but it is still in the document while it fades, and a picture
344
+ * that kept these was found by those queries as though it were the thing it shows.
345
+ *
346
+ * Measured 2026-11-14 on Your Application (morph layout): a closed todo pane's picture kept `data-navigation-back` for the
347
+ * ~650ms it took to leave, so a lookup of the pane's back control found the picture's (#3764 had to wait it out in
348
+ * `browser-nav-zones`). It never took a click (inert, `pointer-events: none`: the point under it hit the list), but
349
+ * the zone's own back control is identified by that attribute, and a picture must not answer to it.
350
+ *
351
+ * Styling hooks (`data-slot`, `data-state`) are NOT here: a picture keeps the look of what it shows. A caller that
352
+ * needs a narrower picture strips more on its own.
353
+ */
354
+ export const SHELL_PICTURE_STRIPPED_ATTRIBUTES: readonly string[] = [
355
+ 'id',
356
+ // The engine's pane and region markers.
357
+ 'data-content-area',
358
+ 'data-panel-id',
359
+ 'data-zone-hidden',
360
+ 'data-zone-emphasized',
361
+ 'data-component-area',
362
+ SHELL_OBJECT_ATTRIBUTE,
363
+ // The engine's control hooks: a zone's back control, an operation's trigger, a navigation item, a rail entry.
364
+ 'data-navigation-back',
365
+ 'data-operation-id',
366
+ 'data-nav-item-id',
367
+ 'data-ref',
368
+ ];
369
+
340
370
  /** The two kinds of ghost. */
341
371
  export enum ShellGhostKind {
342
372
  /** A dismissed side pane, flying away. */
@@ -242,6 +242,20 @@ export const navigationLayoutConfig: NavigationLayout = {
242
242
  transitions: {
243
243
  /* A reference inside the pane stacks in the pane; back returns to the todo beneath. */
244
244
  [CoreResourceOperation.READ]: NavigationTransition.PUSH,
245
+ /*
246
+ * Mutations open a dialog from the pane exactly as they do from the page. A zone's map answers only for
247
+ * navigations started IN that zone (the resolver borrows primary's map for an overlay source, never for a
248
+ * pane), so a pane that named only READ sent "Edit" on a todo to the framework fallback: the form was pushed
249
+ * into the pane, took the todo's place, and wrote its URL (#3764). The layout's stated rule above is
250
+ * "mutations → overlay", and a todo is edited from the pane more often than from anywhere else.
251
+ */
252
+ [CoreResourceOperation.CREATE]: NavigationTransition.OVERLAY,
253
+ [CoreResourceOperation.UPDATE]: NavigationTransition.OVERLAY,
254
+ [CoreResourceOperation.DELETE]: NavigationTransition.OVERLAY,
255
+ [CoreResourceOperation.SEARCH]: NavigationTransition.OVERLAY,
256
+ },
257
+ appearance: {
258
+ overlay: OverlayAppearance.DIALOG,
245
259
  },
246
260
  onEmpty: ZoneEmptyBehavior.COLLAPSE,
247
261
  responsiveCollapse: {