@wildo-ai/framework-knowledge 1.1.13 → 1.1.15

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 (133) 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/esm/framework-knowledge.definitions.d.ts +1 -1
  6. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.definitions.js +9 -0
  8. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  11. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  13. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  15. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  16. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  17. package/dist/knowledge/manifest.json +7 -7
  18. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  19. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  20. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  21. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  22. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  23. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  25. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  27. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  28. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
  29. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  30. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  31. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  32. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  33. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  34. package/dist/knowledge/references/example.config.navigation.full.md +14 -0
  35. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
  36. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
  37. package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
  38. package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
  39. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  40. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  41. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  42. package/dist/knowledge/references/integration-plan.config.md +78 -8
  43. package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
  44. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  45. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  47. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  48. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
  49. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  50. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  51. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  52. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  53. package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
  54. package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
  55. package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
  56. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  59. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  60. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  61. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  62. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  63. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  64. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  65. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  66. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  67. package/dist/knowledge/registries/framework-topics.json +45 -1
  68. package/dist/knowledge/registries/playbooks.json +2 -2
  69. package/dist/knowledge/registries/source-tags.json +1175 -1107
  70. package/dist/knowledge/skills/INDEX.md +2 -2
  71. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
  72. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  73. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  74. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  75. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
  76. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
  77. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  78. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  79. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  80. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  81. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  82. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  83. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
  84. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
  85. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  86. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
  87. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  88. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  89. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  90. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  91. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  92. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  93. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  94. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
  95. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  96. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
  97. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
  98. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  99. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
  100. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  101. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  102. package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
  103. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
  104. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  105. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  106. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  107. package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
  108. package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
  109. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  110. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  111. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  112. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  113. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  114. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  115. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  116. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  117. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
  118. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  119. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  120. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  121. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  122. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  123. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  124. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  125. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  126. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  127. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  128. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  129. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  130. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  131. package/dist/knowledge/topic-index.json +326 -179
  132. package/dist/tsconfig.build.tsbuildinfo +1 -1
  133. package/package.json +4 -4
@@ -30,20 +30,35 @@
30
30
  *
31
31
  * Opt-in. Absent means the application states no residency and nothing is refused, which is not the same as "anywhere":
32
32
  * the documents then say no residency is declared.
33
+ *
34
+ * ## A second, weaker promise: stored at rest (`storedAtRestTerritories`, #2294, decided by Paul 2026-11-15)
35
+ *
36
+ * Most SaaS vendors' "data residency" keeps data AT REST in a region while processing it elsewhere (Notion, Slack,
37
+ * Atlassian, Sentry…), so `territories` refuses them. `storedAtRestTerritories` admits such a vendor when every place its
38
+ * chosen region keeps data at rest (`storageRegionTerritories` on its profile) lies inside it. It is a separate field and
39
+ * never a looser reading of `territories`: a storage-only vendor is never INSIDE the processing residency, its entry says
40
+ * `inside-at-rest`, and the documents state that weaker promise for it by name. Opt-in: absent, nothing changes.
33
41
  */
34
42
  export const ApplicationDataResidencySchema = z
35
43
  .strictObject({
36
44
  /** 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. */
37
- territories: z.array(JurisdictionSlugSchema).min(1),
45
+ territories: z.array(JurisdictionSlugSchema).min(1)
46
+ .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.'),
47
+ /** The places a vendor may keep the data AT REST in while processing it elsewhere (opt-in, the weaker promise). */
48
+ storedAtRestTerritories: z.array(JurisdictionSlugSchema).min(1).optional()
49
+ .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.'),
38
50
  })
39
51
  .superRefine((residency, context) => {
40
- const duplicates = residency.territories.filter((territory, index) => residency.territories.indexOf(territory) !== index);
41
- if (duplicates.length > 0) {
42
- context.addIssue({
43
- code: 'custom',
44
- path: ['territories'],
45
- message: `data residency territory ${[...new Set(duplicates)].map((slug) => `"${slug}"`).join(', ')} is declared more than once`,
46
- });
52
+ for (const field of ['territories', 'storedAtRestTerritories'] as const) {
53
+ const listed = residency[field] ?? [];
54
+ const duplicates = listed.filter((territory, index) => listed.indexOf(territory) !== index);
55
+ if (duplicates.length > 0) {
56
+ context.addIssue({
57
+ code: 'custom',
58
+ path: [field],
59
+ message: `data residency territory ${[...new Set(duplicates)].map((slug) => `"${slug}"`).join(', ')} is declared more than once`,
60
+ });
61
+ }
47
62
  }
48
63
  });
49
64
  export type ApplicationDataResidency = z.infer<typeof ApplicationDataResidencySchema>;
@@ -85,8 +100,20 @@ export function organizationDataResidencyRefusal(
85
100
  + 'narrow: nothing has placed its providers in named places. Declare the application\'s residency first.';
86
101
  }
87
102
  const outside = organization.territories.filter((territory) => !application.territories.some((resident) => jurisdictionReachCovers(resident, territory)));
88
- if (outside.length === 0) return null;
89
- return `The organization's data residency names ${outside.join(', ')}, outside the application's (${application.territories.join(', ')}). `
103
+ if (outside.length > 0) {
104
+ return `The organization's data residency names ${outside.join(', ')}, outside the application's (${application.territories.join(', ')}). `
105
+ + 'An organization can only narrow the application\'s residency: name places inside it.';
106
+ }
107
+ // The weaker promise narrows the same way, and only where the application made it (#2294).
108
+ if (organization.storedAtRestTerritories === undefined) return null;
109
+ if (application.storedAtRestTerritories === undefined) {
110
+ return 'The organization admits vendors on storage at rest (storedAtRestTerritories), and the application does not: an organization '
111
+ + 'can only narrow the application\'s residency. Remove storedAtRestTerritories, or declare it on the application first.';
112
+ }
113
+ const appStored = application.storedAtRestTerritories;
114
+ const storedOutside = organization.storedAtRestTerritories.filter((territory) => !appStored.some((resident) => jurisdictionReachCovers(resident, territory)));
115
+ if (storedOutside.length === 0) return null;
116
+ return `The organization's at-rest residency names ${storedOutside.join(', ')}, outside the application's (${appStored.join(', ')}). `
90
117
  + 'An organization can only narrow the application\'s residency: name places inside it.';
91
118
  }
92
119
 
@@ -140,6 +167,40 @@ export function effectiveDataResidencyTerritories(
140
167
  }
141
168
  return [...kept].sort((left, right) => left.localeCompare(right));
142
169
  }
170
+
171
+ /**
172
+ * The residency a call for an organization must satisfy, both promises narrowed (#2294): the processing territories as
173
+ * {@link effectiveDataResidencyTerritories} computes them, and the at-rest ones the same way when BOTH residencies make
174
+ * that promise. An organization that does not admit storage-only vendors narrows the application's admission away; an
175
+ * application that does not, has nothing for an organization to narrow. `undefined` when the organization declares none.
176
+ */
177
+ export function effectiveDataResidency(
178
+ application: ApplicationDataResidency | undefined,
179
+ organization: OrganizationDataResidency | null | undefined,
180
+ ): ApplicationDataResidency | undefined {
181
+ const territories = effectiveDataResidencyTerritories(application, organization);
182
+ if (territories === undefined) return undefined;
183
+ const storedAtRestTerritories = organization?.storedAtRestTerritories === undefined
184
+ ? undefined
185
+ : application === undefined
186
+ ? [...organization.storedAtRestTerritories]
187
+ : application.storedAtRestTerritories === undefined
188
+ ? undefined
189
+ : narrowedTerritories(application.storedAtRestTerritories, organization.storedAtRestTerritories);
190
+ return { territories: [...territories], ...(storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories }) };
191
+ }
192
+
193
+ /** Every place both lists contain, as the narrower of each pair; sorted. */
194
+ function narrowedTerritories(wider: readonly string[], narrower: readonly string[]): string[] {
195
+ const kept = new Set<string>();
196
+ for (const territory of narrower) {
197
+ for (const resident of wider) {
198
+ if (jurisdictionReachCovers(resident, territory)) kept.add(territory);
199
+ else if (jurisdictionReachCovers(territory, resident)) kept.add(resident);
200
+ }
201
+ }
202
+ return [...kept].sort((left, right) => left.localeCompare(right));
203
+ }
143
204
  ```
144
205
 
145
206
  ### Origin Package: `@wildo-ai/saas-models`
@@ -152,6 +213,12 @@ export function effectiveDataResidencyTerritories(
152
213
  export enum ProviderDataResidencyStatus {
153
214
  /** Every place the chosen region processes in lies inside the residency. */
154
215
  INSIDE = 'inside',
216
+ /**
217
+ * The weaker promise (`storedAtRestTerritories`, opt-in): the chosen region processes outside the residency, or nothing
218
+ * says where it processes, and every place it keeps data AT REST lies inside the at-rest territories. Admitted, and
219
+ * never INSIDE: the documents say the vendor stores the data in the region and processes it elsewhere.
220
+ */
221
+ INSIDE_AT_REST = 'inside-at-rest',
155
222
  /** The chosen region processes in at least one place outside the residency. */
156
223
  OUTSIDE = 'outside',
157
224
  /** The profile does not state which places the chosen region covers (a global region, or a map not yet researched). */
@@ -223,9 +290,30 @@ export interface ProviderDataResidencyEntry {
223
290
  readonly territories: readonly string[] | null;
224
291
  /** The places outside the residency, for {@link ProviderDataResidencyStatus.OUTSIDE}; empty otherwise. */
225
292
  readonly outsideTerritories: readonly string[];
293
+ /** The places the region keeps data at rest in, for {@link ProviderDataResidencyStatus.INSIDE_AT_REST}; `null` otherwise. */
294
+ readonly storageTerritories?: readonly string[] | null;
295
+ /**
296
+ * The account condition {@link storageTerritories} holds on (#3920), for {@link ProviderDataResidencyStatus.INSIDE_AT_REST}:
297
+ * what the operator attested by choosing the region. `null` when the map holds on the choice alone.
298
+ */
299
+ readonly storageCondition?: string | null;
226
300
  readonly status: ProviderDataResidencyStatus;
227
301
  }
228
302
 
303
+ /**
304
+ * Whether a provider at this status may be used under the residency (#2294): INSIDE, or INSIDE_AT_REST, the weaker promise
305
+ * the application opted into. Every admission site reads this, so a status added later is refused until it is placed here.
306
+ *
307
+ * A type guard, so a caller that returns early on an admitted status keeps an exhaustive switch over the rest (the
308
+ * placement below does): a plain boolean would leave INSIDE and INSIDE_AT_REST in the switch's type, which a strict
309
+ * program reports as a missing return.
310
+ */
311
+ export function providerDataResidencyAdmits(
312
+ status: ProviderDataResidencyStatus,
313
+ ): status is ProviderDataResidencyStatus.INSIDE | ProviderDataResidencyStatus.INSIDE_AT_REST {
314
+ return status === ProviderDataResidencyStatus.INSIDE || status === ProviderDataResidencyStatus.INSIDE_AT_REST;
315
+ }
316
+
229
317
  /** What the residency reads of a provider choice: who runs it, and in which region. */
230
318
  export type ProviderDataResidencyChoice = Pick<ApplicationProviderComplianceChoice, 'deploymentModel' | 'processingRegion'>;
231
319
 
@@ -295,6 +383,8 @@ function providerDataResidencyEntryOf(input: {
295
383
  processingRegion: choice.processingRegion,
296
384
  profileEstablished: established !== null,
297
385
  regionTerritories: established?.processingRegionTerritories?.[choice.processingRegion] ?? null,
386
+ regionStorageTerritories: established?.storageRegionTerritories?.[choice.processingRegion] ?? null,
387
+ regionStorageCondition: established?.storageRegionConditions?.[choice.processingRegion] ?? null,
298
388
  residency,
299
389
  });
300
390
  }
@@ -305,21 +395,37 @@ function vendorRegionDataResidencyEntry(input: {
305
395
  readonly processingRegion: string;
306
396
  readonly profileEstablished: boolean;
307
397
  readonly regionTerritories: readonly string[] | null;
398
+ readonly regionStorageTerritories: readonly string[] | null;
399
+ readonly regionStorageCondition: string | null;
308
400
  readonly residency: ApplicationDataResidency;
309
401
  }): ProviderDataResidencyEntry {
310
402
  const base = { providerRef: input.providerRef, processingRegion: input.processingRegion };
311
403
  if (!input.profileEstablished) {
312
404
  return { ...base, territories: null, outsideTerritories: [], status: ProviderDataResidencyStatus.NO_ESTABLISHED_PROFILE };
313
405
  }
314
- if (input.regionTerritories === null) {
315
- return { ...base, territories: null, outsideTerritories: [], status: ProviderDataResidencyStatus.TERRITORY_UNKNOWN };
316
- }
317
- const outsideTerritories = territoriesOutsideDataResidency(input.regionTerritories, input.residency);
406
+ const processing: ProviderDataResidencyEntry = input.regionTerritories === null
407
+ ? { ...base, territories: null, outsideTerritories: [], status: ProviderDataResidencyStatus.TERRITORY_UNKNOWN }
408
+ : (() => {
409
+ const outsideTerritories = territoriesOutsideDataResidency(input.regionTerritories, input.residency);
410
+ return {
411
+ ...base,
412
+ territories: [...input.regionTerritories],
413
+ outsideTerritories,
414
+ status: outsideTerritories.length === 0 ? ProviderDataResidencyStatus.INSIDE : ProviderDataResidencyStatus.OUTSIDE,
415
+ };
416
+ })();
417
+ // The processing promise first, always: a region inside it is INSIDE whatever it stores. The weaker one is asked only
418
+ // of a region the processing promise refuses, and only when the application opted into it (#2294).
419
+ if (processing.status === ProviderDataResidencyStatus.INSIDE) return processing;
420
+ const atRest = input.residency.storedAtRestTerritories;
421
+ if (atRest === undefined || input.regionStorageTerritories === null) return processing;
422
+ const storedOutside = input.regionStorageTerritories.filter((territory) => !atRest.some((resident) => jurisdictionReachCovers(resident, territory)));
423
+ if (storedOutside.length > 0) return processing;
318
424
  return {
319
- ...base,
320
- territories: [...input.regionTerritories],
321
- outsideTerritories,
322
- status: outsideTerritories.length === 0 ? ProviderDataResidencyStatus.INSIDE : ProviderDataResidencyStatus.OUTSIDE,
425
+ ...processing,
426
+ storageTerritories: [...input.regionStorageTerritories],
427
+ storageCondition: input.regionStorageCondition,
428
+ status: ProviderDataResidencyStatus.INSIDE_AT_REST,
323
429
  };
324
430
  }
325
431
 
@@ -340,6 +446,8 @@ export function dataResidencyEntriesOf(
340
446
  processingRegion: entry.choice.processingRegion!,
341
447
  profileEstablished: entry.offered !== null,
342
448
  regionTerritories: entry.regionTerritories,
449
+ regionStorageTerritories: entry.regionStorageTerritories,
450
+ regionStorageCondition: entry.regionStorageCondition,
343
451
  residency,
344
452
  }));
345
453
  }
@@ -385,6 +493,13 @@ export interface ProviderDataResidencyPlacement {
385
493
  readonly outcome: ProviderDataResidencyPlacementOutcome;
386
494
  /** The provider's vendor regions whose stated places all lie inside the residency, in the profile's order. */
387
495
  readonly regionsInside: readonly string[];
496
+ /**
497
+ * The vendor regions admitted only on the weaker promise (#3876): every place the region keeps data at rest lies inside
498
+ * the residency's `storedAtRestTerritories`, while it processes elsewhere. Empty when the residency declares no at-rest
499
+ * list, and never a region already in {@link regionsInside}. Read only when no region processes inside: a placement
500
+ * offers the stronger promise first.
501
+ */
502
+ readonly regionsInsideAtRest: readonly string[];
388
503
  /** The choice to write, for {@link ProviderDataResidencyPlacementOutcome.DERIVED} only. */
389
504
  readonly derivedChoice?: { readonly deploymentModel: ProviderDeploymentModel.VENDOR_HOSTED; readonly processingRegion: string };
390
505
  }
@@ -399,10 +514,16 @@ export interface ProviderDataResidencyPlacement {
399
514
  * Derived only when the residency leaves no choice: the provider is only offered vendor-hosted, exactly one of its
400
515
  * regions processes wholly inside, and no authored choice names a region. Everything else is a decision, and is
401
516
  * returned with the regions that would satisfy the residency so whoever takes it sees the options.
517
+ *
518
+ * When the application also declares an at-rest residency (#3876), a provider with NO region processing inside is placed
519
+ * on the weaker promise instead: derived when exactly one of its regions keeps everything at rest inside
520
+ * `storedAtRestTerritories`, a choice when several do. A region that processes inside always wins, because it keeps the
521
+ * stronger promise; a placement never trades it for a storage-only one.
402
522
  */
403
523
  export function placeProvidersInsideDataResidency(params: Parameters<typeof assessProviderProcessingAgainstDataResidency>[0]): readonly ProviderDataResidencyPlacement[] {
404
524
  return assessProviderProcessingAgainstDataResidency(params).flatMap((assessment): ProviderDataResidencyPlacement[] => {
405
- if (assessment.status === ProviderDataResidencyStatus.INSIDE) return [];
525
+ // An admitted provider needs no placement; an INSIDE_AT_REST one is admitted on the weaker promise the application made.
526
+ if (providerDataResidencyAdmits(assessment.status)) return [];
406
527
  const profile = Object.hasOwn(params.profilesByProviderRef, assessment.providerRef) ? params.profilesByProviderRef[assessment.providerRef] : undefined;
407
528
  const established = establishedProviderComplianceProfile(profile);
408
529
  const regionsInside = established === null
@@ -411,8 +532,15 @@ export function placeProvidersInsideDataResidency(params: Parameters<typeof asse
411
532
  const territories = established.processingRegionTerritories?.[region];
412
533
  return territories !== undefined && territoriesOutsideDataResidency(territories, params.residency).length === 0;
413
534
  });
535
+ const atRest = params.residency.storedAtRestTerritories;
536
+ const regionsInsideAtRest = established === null || atRest === undefined
537
+ ? []
538
+ : established.processingRegions.filter((region) => {
539
+ const stored = established.storageRegionTerritories?.[region];
540
+ return !regionsInside.includes(region) && stored !== undefined && territoriesOutsideDataResidency(stored, { territories: atRest }).length === 0;
541
+ });
414
542
  const placement = (outcome: ProviderDataResidencyPlacementOutcome): ProviderDataResidencyPlacement[] => [
415
- { providerRef: assessment.providerRef, assessment, outcome, regionsInside },
543
+ { providerRef: assessment.providerRef, assessment, outcome, regionsInside, regionsInsideAtRest },
416
544
  ];
417
545
  switch (assessment.status) {
418
546
  case ProviderDataResidencyStatus.NO_ESTABLISHED_PROFILE:
@@ -431,14 +559,17 @@ export function placeProvidersInsideDataResidency(params: Parameters<typeof asse
431
559
  if (assessment.status === ProviderDataResidencyStatus.NO_CHOICE && established.deploymentModels.includes(ProviderDeploymentModel.SELF_HOSTED)) {
432
560
  return placement(ProviderDataResidencyPlacementOutcome.DEPLOYMENT_MODEL_IS_A_CHOICE);
433
561
  }
434
- if (regionsInside.length === 0) return placement(ProviderDataResidencyPlacementOutcome.NO_REGION_INSIDE);
435
- if (regionsInside.length > 1) return placement(ProviderDataResidencyPlacementOutcome.SEVERAL_REGIONS_INSIDE);
562
+ // The stronger promise first: a region processing inside is never traded for one that only stores inside.
563
+ const candidates = regionsInside.length > 0 ? regionsInside : regionsInsideAtRest;
564
+ if (candidates.length === 0) return placement(ProviderDataResidencyPlacementOutcome.NO_REGION_INSIDE);
565
+ if (candidates.length > 1) return placement(ProviderDataResidencyPlacementOutcome.SEVERAL_REGIONS_INSIDE);
436
566
  return [{
437
567
  providerRef: assessment.providerRef,
438
568
  assessment,
439
569
  outcome: ProviderDataResidencyPlacementOutcome.DERIVED,
440
570
  regionsInside,
441
- derivedChoice: { deploymentModel: ProviderDeploymentModel.VENDOR_HOSTED, processingRegion: regionsInside[0]! },
571
+ regionsInsideAtRest,
572
+ derivedChoice: { deploymentModel: ProviderDeploymentModel.VENDOR_HOSTED, processingRegion: candidates[0]! },
442
573
  }];
443
574
  }
444
575
  }
@@ -453,16 +584,25 @@ export function placeProvidersInsideDataResidency(params: Parameters<typeof asse
453
584
  */
454
585
  export function dataResidencyPlacementStatement(placement: ProviderDataResidencyPlacement, residency: ApplicationDataResidency): string {
455
586
  const declared = residency.territories.join(', ');
587
+ const atRest = residency.storedAtRestTerritories?.join(', ');
456
588
  const at = `providerComplianceChoices.${placement.providerRef}`;
457
- const inside = placement.regionsInside.map((region) => `"${region}"`).join(', ');
589
+ // The candidates a placement chose among: the regions processing inside, else (#3876) the ones storing inside at rest.
590
+ const onlyAtRest = placement.regionsInside.length === 0 && placement.regionsInsideAtRest.length > 0;
591
+ const inside = (onlyAtRest ? placement.regionsInsideAtRest : placement.regionsInside).map((region) => `"${region}"`).join(', ');
458
592
  switch (placement.outcome) {
459
593
  case ProviderDataResidencyPlacementOutcome.DERIVED:
460
- return `Provider "${placement.providerRef}" processes in region "${placement.derivedChoice?.processingRegion}", the only one of its regions inside the data residency (${declared}).`;
594
+ return onlyAtRest
595
+ ? `Provider "${placement.providerRef}" uses region "${placement.derivedChoice?.processingRegion}", the only one of its regions keeping data at rest inside the at-rest residency (${atRest}). `
596
+ + `It processes outside the data residency (${declared}), so it is admitted on the weaker promise and the documents say so.`
597
+ : `Provider "${placement.providerRef}" processes in region "${placement.derivedChoice?.processingRegion}", the only one of its regions inside the data residency (${declared}).`;
461
598
  case ProviderDataResidencyPlacementOutcome.SEVERAL_REGIONS_INSIDE:
462
- return `Provider "${placement.providerRef}" has several regions inside the data residency (${declared}): ${inside}. Choose one as ${at}.processingRegion (deploymentModel VENDOR_HOSTED).`;
599
+ return onlyAtRest
600
+ ? `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).`
601
+ : `Provider "${placement.providerRef}" has several regions inside the data residency (${declared}): ${inside}. Choose one as ${at}.processingRegion (deploymentModel VENDOR_HOSTED).`;
463
602
  case ProviderDataResidencyPlacementOutcome.NO_REGION_INSIDE:
464
- return `Provider "${placement.providerRef}" has no region its profile states to process wholly inside the data residency (${declared}). `
465
- + 'Replace it with a provider that does, run it self-hosted if it is offered that way, or widen the residency.';
603
+ return `Provider "${placement.providerRef}" has no region its profile states to process wholly inside the data residency (${declared})`
604
+ + (atRest === undefined ? '' : `, nor to keep data at rest wholly inside the at-rest residency (${atRest})`)
605
+ + '. Replace it with a provider that does, run it self-hosted if it is offered that way, or widen the residency.';
466
606
  case ProviderDataResidencyPlacementOutcome.DEPLOYMENT_MODEL_IS_A_CHOICE:
467
607
  return `Provider "${placement.providerRef}" can be run by its vendor or by you: decide which as ${at}.deploymentModel`
468
608
  + (placement.regionsInside.length === 0 ? ` (none of its vendor regions lies inside the data residency, ${declared}).` : ` (vendor regions inside the data residency, ${declared}: ${inside}).`);
@@ -496,6 +636,7 @@ export function dataResidencyRefusalOf(
496
636
  : `providerComplianceChoices.${entry.providerRef}.processingRegion "${entry.processingRegion}"`;
497
637
  switch (entry.status) {
498
638
  case ProviderDataResidencyStatus.INSIDE:
639
+ case ProviderDataResidencyStatus.INSIDE_AT_REST:
499
640
  return null;
500
641
  case ProviderDataResidencyStatus.OUTSIDE:
501
642
  return `${where} processes in ${entry.outsideTerritories.join(', ')}, outside the declared data residency (${declared}). `
@@ -539,13 +680,14 @@ export function dataResidencyRefusalOf(
539
680
  * places goes only to a processor whose chosen region processes inside them.
540
681
  */
541
682
  export function assessProviderCallAgainstDataResidency(params: {
542
- readonly territories: readonly string[];
683
+ /** The residency the call must satisfy: both promises, narrowed for the organization ({@link effectiveDataResidency}). */
684
+ readonly residency: ApplicationDataResidency;
543
685
  readonly providerRef: string;
544
686
  readonly choice: ProviderDataResidencyChoice | undefined;
545
687
  readonly profile: ProviderComplianceProfile | undefined;
546
688
  readonly account: ProviderCallAccount;
547
689
  }): ProviderDataResidencyEntry | null {
548
- const residency: ApplicationDataResidency = { territories: [...params.territories] as ApplicationDataResidency['territories'] };
690
+ const { residency } = params;
549
691
  if (params.account === ProviderCallAccount.OWNER) {
550
692
  const established = establishedProviderComplianceProfile(params.profile);
551
693
  if (established !== null && providerIsAlwaysSelfHosted(established)) return null;
@@ -604,6 +746,8 @@ export function dataResidencyRefusals(entries: readonly ProviderDataResidencyEnt
604
746
  */
605
747
  export const RuntimeProviderDataResidencySchema = z.strictObject({
606
748
  territories: z.array(JurisdictionSlugSchema).min(1),
749
+ /** The opt-in at-rest territories (#2294), carried only when the application declares them. */
750
+ storedAtRestTerritories: z.array(JurisdictionSlugSchema).min(1).optional(),
607
751
  choices: z.record(z.string().min(1), z.strictObject({
608
752
  deploymentModel: z.enum(ProviderDeploymentModel),
609
753
  processingRegion: z.string().min(1).optional(),
@@ -621,6 +765,7 @@ export function runtimeProviderDataResidencyFor(input: {
621
765
  const choices = input.choices ?? {};
622
766
  return {
623
767
  territories: [...input.residency.territories],
768
+ ...(input.residency.storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories: [...input.residency.storedAtRestTerritories] }),
624
769
  choices: Object.fromEntries([...new Set(input.providerRefs)].sort((left, right) => left.localeCompare(right))
625
770
  .filter((providerRef) => Object.hasOwn(choices, providerRef))
626
771
  .map((providerRef) => {
@@ -645,10 +790,22 @@ export function narrowRuntimeProviderDataResidency(
645
790
  if (runtime === undefined) return undefined;
646
791
  return {
647
792
  territories: [...runtime.territories],
793
+ ...(runtime.storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories: [...runtime.storedAtRestTerritories] }),
648
794
  choices: Object.fromEntries(Object.entries(runtime.choices).filter(([providerRef]) => providerRefs.includes(providerRef))),
649
795
  };
650
796
  }
651
797
 
798
+ /**
799
+ * The application's declared residency as a runtime artifact carries it, both promises (#2294). The one reading the
800
+ * loader's re-check and the per-organization gate share, so neither can drop the at-rest territories the other applies.
801
+ */
802
+ export function applicationDataResidencyOfRuntime(runtime: RuntimeProviderDataResidency): ApplicationDataResidency {
803
+ return {
804
+ territories: [...runtime.territories],
805
+ ...(runtime.storedAtRestTerritories === undefined ? {} : { storedAtRestTerritories: [...runtime.storedAtRestTerritories] }),
806
+ };
807
+ }
808
+
652
809
  /**
653
810
  * The residency a runtime re-applies at load, over the providers it loaded: `providerRef` -> the refusal, for every one
654
811
  * that is not inside. The backend provider loader leaves each unresolved, so startup refuses naming it.
@@ -658,7 +815,7 @@ export function runtimeDataResidencyRefusalsByProvider(input: {
658
815
  readonly providerRefs: readonly string[];
659
816
  readonly profilesByProviderRef: Readonly<Record<string, ProviderComplianceProfile | undefined>>;
660
817
  }): ReadonlyMap<string, string> {
661
- const residency: ApplicationDataResidency = { territories: input.runtime.territories };
818
+ const residency = applicationDataResidencyOfRuntime(input.runtime);
662
819
  const refusals = new Map<string, string>();
663
820
  // Only the providers this host LOADED: a choice for one that failed to load for another reason must not replace that
664
821
  // reason, and a provider that is not loaded receives no call.
@@ -58,6 +58,13 @@ export const PROVIDER_CAPABILITY_DISCLOSURES: Readonly<Record<BuiltinProviderCap
58
58
  carriedBy: 'each signer\'s name and email address, and the document sent for signature, which the vendor holds signed',
59
59
  linkableToSubjectByApplication: true,
60
60
  },
61
+ // Embedded signing: the signer's name and e-mail again, to open their signing page, and the page the vendor serves in a
62
+ // frame of the application, which reaches the vendor from the signer's browser with the application's origin.
63
+ [BUILTIN_PROVIDER_CAPABILITY.EMBEDDED_ELECTRONIC_SIGNATURE]: {
64
+ categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS],
65
+ carriedBy: 'each signer\'s name and email address, sent again to open their signing page, and the signer\'s browser, which loads that page from the vendor',
66
+ linkableToSubjectByApplication: true,
67
+ },
61
68
  [BUILTIN_PROVIDER_CAPABILITY.BILLING]: {
62
69
  categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS, PersonalDataCategory.FINANCIAL],
63
70
  carriedBy: 'the customer name and email address, and the payment, subscription and invoice records',
@@ -41,6 +41,17 @@ export const BUILTIN_PROVIDER_CAPABILITY = {
41
41
  * levels its contract declares. Maps to `EngineCapability.ELECTRONIC_SIGNATURE`.
42
42
  */
43
43
  ELECTRONIC_SIGNATURE: 'ELECTRONIC_SIGNATURE',
44
+ /**
45
+ * Provider ALSO lets a signer sign inside the application, in a frame showing the vendor's signing page, instead of
46
+ * from the vendor's e-mail (embedded signing). Maps to `EngineCapability.ELECTRONIC_SIGNATURE`, the slot it shares with
47
+ * {@link ELECTRONIC_SIGNATURE}, and is claimed only beside it.
48
+ *
49
+ * A token of its own because vendors split here: DocuSign, Yousign, BoldSign, SignNow and Adobe Acrobat Sign answer a
50
+ * signing page URL the application can frame; IgniSign, Dropbox Sign and Universign need their own browser script, so
51
+ * their providers sign from the e-mail only. The claim is the provider's statement that its contract declares
52
+ * `embeddedSigning`; the engine refuses at startup a claim with no such declaration.
53
+ */
54
+ EMBEDDED_ELECTRONIC_SIGNATURE: 'EMBEDDED_ELECTRONIC_SIGNATURE',
44
55
  /**
45
56
  * Single billing-engagement capability covering everything from
46
57
  * Checkout-style hosted flows to first-party PaymentIntent flows.
@@ -179,6 +179,13 @@ export interface ProviderComplianceChoiceAssessmentEntry {
179
179
  * region is chosen or the profile does not map it.
180
180
  */
181
181
  readonly regionTerritories: readonly string[] | null;
182
+ /**
183
+ * The places the chosen region keeps data at rest in, from the profile's `storageRegionTerritories` (#2294). `null` when
184
+ * no region is chosen or the profile does not map its storage.
185
+ */
186
+ readonly regionStorageTerritories: readonly string[] | null;
187
+ /** The condition the chosen region's storage map holds on, from `storageRegionConditions` (#3920); `null` when none. */
188
+ readonly regionStorageCondition: string | null;
182
189
  }
183
190
 
184
191
  /** Assess ONE choice against the provider's profile. See {@link ProviderComplianceChoiceAssessment}. */
@@ -222,6 +229,8 @@ export function assessProviderComplianceChoices(params: {
222
229
  offered: established === null ? null : { deploymentModels: established.deploymentModels, processingRegions: established.processingRegions },
223
230
  regionReach: choice.processingRegion === undefined ? null : established?.processingRegionReach?.[choice.processingRegion]?.kind ?? null,
224
231
  regionTerritories: choice.processingRegion === undefined ? null : established?.processingRegionTerritories?.[choice.processingRegion] ?? null,
232
+ regionStorageTerritories: choice.processingRegion === undefined ? null : established?.storageRegionTerritories?.[choice.processingRegion] ?? null,
233
+ regionStorageCondition: choice.processingRegion === undefined ? null : established?.storageRegionConditions?.[choice.processingRegion] ?? null,
225
234
  };
226
235
  });
227
236
  }
@@ -15,10 +15,17 @@
15
15
  *
16
16
  * The engine calls `enabledCondition` in TWO places with these parameters, so one function decides both: in the frontend
17
17
  * before it offers the action (a list judges each SUMMARY row, a record page the full row), and in the backend before the
18
- * operation runs, where a `false` refuses the call with 403 `service_resource_operation_disabled` before any hook. So a
18
+ * operation runs, where a `false` refuses the call with `service_resource_operation_disabled` before any hook. So a
19
19
  * condition must say EVERYTHING the operation's handler would refuse on the row's state or on who is asking, or the
20
20
  * action is offered and then refused.
21
21
  *
22
+ * The refusal's status follows what the condition READ on its way to `false`: only the row (and `objectContext`) is a
23
+ * refusal of the state, 409 Conflict; a read of `initiatorIds`, `initiatorUserContext` or `inputDto` may be a refusal of
24
+ * the caller, 403 Forbidden. `&&` stops at the first false operand, so write the state check FIRST
25
+ * (`currentObject.status === PENDING && currentObject.requestedByUserId !== initiatorIds.userId`): a refusal on the
26
+ * status then never reads the caller and answers 409. On a CREATE-shaped operation `currentObject` is the request body, so
27
+ * a refusal there is never a state conflict: 403.
28
+ *
22
29
  * - `currentObject` — the row as it stands. On a list row only its summary fields and the variant's
23
30
  * `enabledConditionFields` are present.
24
31
  * - `initiatorIds.userId` — the person asking (absent for a machine principal). Compare it with an owner field to offer an
@@ -256,6 +256,36 @@ export enum SystemOfRecordErrorCode {
256
256
  */
257
257
  WRITE_FIELD_NOT_WRITABLE = 'SYSTEM_OF_RECORD_WRITE_FIELD_NOT_WRITABLE',
258
258
 
259
+ /**
260
+ * REQUEST — a create or update refused, with a CONFIGURATION error type, because the binding maps a field onto a
261
+ * remote field the system of record COMPUTES and does not store, so a
262
+ * write to it would be accepted and discarded (#3953). Odoo answers `true` to a `create` or `write` naming such a field
263
+ * and keeps nothing: measured on Odoo 19.0, `res.partner.country_code` (related to `country_id.code`) written alone
264
+ * read back `false`. Refused before anything is sent, because the alternative is a write reported as done that changed
265
+ * nothing. The context names the field and, when the system of record says so, the field it is computed from
266
+ * (`computedFrom`), which is the one to write.
267
+ *
268
+ * Not the caller's to fix: the binding's mapping is wrong for writes, so it is a configuration error.
269
+ */
270
+ WRITE_FIELD_COMPUTED_REMOTELY = 'SYSTEM_OF_RECORD_WRITE_FIELD_COMPUTED_REMOTELY',
271
+
272
+ /**
273
+ * REQUEST — a field written through a lookup (`fieldMappings[].writeThrough`, #3953) holds a value no record of the
274
+ * lookup model matches (an ISO country code Odoo does not know, or `'fr'` where the records hold `'FR'`: the match is
275
+ * exact). Refused before anything is sent: writing nothing would report the field as written, and writing a guess
276
+ * would put the row in the wrong place. The context names the field, the lookup model and the value.
277
+ */
278
+ WRITE_VALUE_UNRESOLVED = 'SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED',
279
+
280
+ /**
281
+ * REQUEST — a create or update refused, with a CONFIGURATION error type, because a field's write-through lookup
282
+ * (`fieldMappings[].writeThrough`, #3953) cannot name ONE record: the
283
+ * value matches several records of the lookup model (the lookup field does not identify a record), a match carries no
284
+ * integer id, or the field written is not a many2one to the lookup model as the system of record describes it. The
285
+ * binding's fault, not the caller's; nothing is sent. The context names the field, the lookup model and why.
286
+ */
287
+ WRITE_LOOKUP_INVALID = 'SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID',
288
+
259
289
  /**
260
290
  * REQUEST — the write was SENT and nobody knows whether the system of record applied it: the call
261
291
  * timed out, the connection dropped after the request left, or a gateway answered for the vendor.
@@ -25,7 +25,9 @@
25
25
  * return the passage. A passage found only by the lexical arm carries no `vectorRank`, and every
26
26
  * passage in a lexical-only call carries none — which is the expected state when the application
27
27
  * configures no embeddings provider, or when text was committed more recently than the background
28
- * worker has embedded it.
28
+ * worker has embedded it. Such a not-yet-embedded passage is not ranked BELOW embedded ones for that
29
+ * reason alone: when the vector arm ran and could not rank it, its `fusion` counts its lexical rank for
30
+ * both arms, so text written a minute ago competes on its wording from the moment it is committed.
29
31
  *
30
32
  * @example
31
33
  * // Show the strongest passages, and say WHY each was found.
@@ -42,7 +44,7 @@
42
44
  export interface RagChunkRetrievalScores {
43
45
  /** Reciprocal-rank-fusion score. Ordering key. Not a probability and not comparable across queries. */
44
46
  fusion: number;
45
- /** 1-based rank within the vector arm, absent when that arm did not return this chunk. */
47
+ /** 1-based rank within the vector arm, absent when that arm did not return this chunk (never imputed). */
46
48
  vectorRank?: number;
47
49
  /** Cosine similarity in `[-1, 1]` (`1 - cosine_distance`). Absent with the rank. */
48
50
  vectorSimilarity?: number;
@@ -271,6 +271,16 @@ const ProcessorIdentityFieldsSchema = z.object({
271
271
  * `Ireland`, `United States`), and a fixed list would be wrong for the next vendor.
272
272
  */
273
273
  processingRegions: z.array(z.string().trim().min(1)).min(1),
274
+ /**
275
+ * Where this processor keeps the data AT REST, when that differs from where it processes it (#3921): a vendor admitted
276
+ * on the application's opt-in at-rest residency stores in one place and processes in another, and a register that
277
+ * named only the processing region could not say the half a reader of the weaker promise needs.
278
+ *
279
+ * In the operator's words, like {@link processingRegions}. The framework SUGGESTS it from the vendor profile's storage
280
+ * map for the chosen region, and the operator adopts it by committing it here, like every other vendor fact (#1744).
281
+ * Absent means not stated; the international-transfers fact names every `inside-at-rest` provider whose entry lacks it.
282
+ */
283
+ storedAtRestIn: z.array(z.string().trim().min(1)).min(1).optional(),
274
284
  /**
275
285
  * The processor's own subprocessors.
276
286
  *
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "assurance-authority-bases",
3
3
  "metadata": {
4
- "generatedAt": "2026-11-14T09:36:56.594Z",
4
+ "generatedAt": "2026-11-17T16:03:09.086Z",
5
5
  "description": "Compiled portable assurance-authority bases."
6
6
  },
7
7
  "entries": {
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "framework-topics",
3
3
  "metadata": {
4
- "generatedAt": "2026-11-14T09:36:56.594Z",
4
+ "generatedAt": "2026-11-17T16:03:09.086Z",
5
5
  "description": "Topic registry derived from extracted framework-knowledge tags."
6
6
  },
7
7
  "entries": {
@@ -4527,6 +4527,17 @@
4527
4527
  "referenceFilePath": "references/saas.frontend.domain-module.md",
4528
4528
  "sourceReferenceCount": 1
4529
4529
  },
4530
+ "saas.frontend.electronic-signatures.embedded-signing-frame": {
4531
+ "topicId": "saas.frontend.electronic-signatures.embedded-signing-frame",
4532
+ "title": "Saas Frontend Electronic Signatures Embedded Signing Frame",
4533
+ "categories": [
4534
+ "saas",
4535
+ "saas.frontend",
4536
+ "saas.frontend.electronic-signatures"
4537
+ ],
4538
+ "referenceFilePath": "references/saas.frontend.electronic-signatures.embedded-signing-frame.md",
4539
+ "sourceReferenceCount": 1
4540
+ },
4530
4541
  "saas.frontend.embedded-resource-descent": {
4531
4542
  "topicId": "saas.frontend.embedded-resource-descent",
4532
4543
  "title": "Saas Frontend Embedded Resource Descent",
@@ -5743,6 +5754,17 @@
5743
5754
  "referenceFilePath": "references/saas.models.flows-actors.human-input-form.md",
5744
5755
  "sourceReferenceCount": 1
5745
5756
  },
5757
+ "saas.models.flows-actors.mcp-server-declaration": {
5758
+ "topicId": "saas.models.flows-actors.mcp-server-declaration",
5759
+ "title": "Saas Models Flows Actors Mcp Server Declaration",
5760
+ "categories": [
5761
+ "saas",
5762
+ "saas.models",
5763
+ "saas.models.flows-actors"
5764
+ ],
5765
+ "referenceFilePath": "references/saas.models.flows-actors.mcp-server-declaration.md",
5766
+ "sourceReferenceCount": 1
5767
+ },
5746
5768
  "saas.models.flows-actors.operation-approval-pending": {
5747
5769
  "topicId": "saas.models.flows-actors.operation-approval-pending",
5748
5770
  "title": "Saas Models Flows Actors Operation Approval Pending",
@@ -5765,6 +5787,28 @@
5765
5787
  "referenceFilePath": "references/saas.models.flows-actors.operation-approval-requirement.md",
5766
5788
  "sourceReferenceCount": 1
5767
5789
  },
5790
+ "saas.models.flows-actors.outbound-credential": {
5791
+ "topicId": "saas.models.flows-actors.outbound-credential",
5792
+ "title": "Saas Models Flows Actors Outbound Credential",
5793
+ "categories": [
5794
+ "saas",
5795
+ "saas.models",
5796
+ "saas.models.flows-actors"
5797
+ ],
5798
+ "referenceFilePath": "references/saas.models.flows-actors.outbound-credential.md",
5799
+ "sourceReferenceCount": 1
5800
+ },
5801
+ "saas.models.flows-actors.remote-agent-declaration": {
5802
+ "topicId": "saas.models.flows-actors.remote-agent-declaration",
5803
+ "title": "Saas Models Flows Actors Remote Agent Declaration",
5804
+ "categories": [
5805
+ "saas",
5806
+ "saas.models",
5807
+ "saas.models.flows-actors"
5808
+ ],
5809
+ "referenceFilePath": "references/saas.models.flows-actors.remote-agent-declaration.md",
5810
+ "sourceReferenceCount": 1
5811
+ },
5768
5812
  "saas.models.flows-actors.review-calendar": {
5769
5813
  "topicId": "saas.models.flows-actors.review-calendar",
5770
5814
  "title": "Saas Models Flows Actors Review Calendar",