@wildo-ai/framework-knowledge 1.1.1 → 1.1.3

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 (223) hide show
  1. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  2. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  3. package/dist/esm/framework-knowledge.definitions.js +271 -8
  4. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  5. package/dist/esm/framework-knowledge.loader.d.ts +19 -0
  6. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.loader.js +32 -0
  8. package/dist/esm/framework-knowledge.loader.js.map +1 -1
  9. package/dist/esm/framework-knowledge.schemas.d.ts +13 -2
  10. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  11. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +45 -0
  13. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -0
  14. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +55 -0
  15. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -0
  16. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +6 -7
  17. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  18. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +6 -6
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  20. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -4
  21. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  22. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -2
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  24. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -4
  25. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  26. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -2
  27. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +3 -9
  29. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +1 -3
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +10 -6
  33. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +25 -4
  35. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  36. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +1 -5
  37. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +1 -3
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +4 -2
  41. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  42. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +4 -2
  43. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -2
  45. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -14
  47. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  48. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +3 -5
  49. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  50. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +3 -4
  51. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  52. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +2 -8
  53. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  54. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -2
  55. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  56. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +2 -8
  57. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  58. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -2
  59. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  60. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +52 -0
  61. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -0
  62. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +127 -0
  63. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -0
  64. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +75 -0
  65. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -0
  66. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +91 -0
  67. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -0
  68. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +29 -0
  69. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  70. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +28 -0
  71. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -0
  72. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +9 -45
  73. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +4 -54
  75. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  76. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +30 -0
  77. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -0
  78. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +25 -0
  79. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -0
  80. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +2 -9
  81. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  82. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +9 -5
  83. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +0 -1
  85. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  86. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +0 -1
  87. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
  88. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +0 -1
  89. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  90. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +0 -1
  91. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
  92. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -9
  93. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  94. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -2
  95. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  96. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +2 -8
  97. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -2
  99. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  100. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -8
  101. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  102. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -2
  103. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  104. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +2 -8
  105. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  106. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +5 -4
  107. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  108. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -4
  109. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  110. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -2
  111. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  112. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +4 -6
  113. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +25 -5
  115. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  116. package/dist/knowledge/manifest.json +6 -7
  117. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +7 -47
  118. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +6 -13
  119. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +1 -82
  120. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +11 -6
  121. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +10 -5
  122. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +3 -4
  123. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +3 -4
  124. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -735
  125. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +11 -7
  126. package/dist/knowledge/playbooks/refinement.document-facts/method.md +16 -123
  127. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +15 -8
  128. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +10 -4
  129. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +10 -4
  130. package/dist/knowledge/playbooks/top_down.capability-map/method.md +2 -2
  131. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +12 -5
  132. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +10 -4
  133. package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-protocol.json +1 -1
  134. package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-treatment.json +1 -1
  135. package/dist/knowledge/playbooks/top_down.market-analysis/method.md +165 -51
  136. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +39 -21
  137. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +2 -6
  138. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +10 -4
  139. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +1 -1
  140. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +11 -5
  141. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +2 -2
  142. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +11 -5
  143. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +10 -4
  144. package/dist/knowledge/references/build-plan.task-graph.config.md +1 -45
  145. package/dist/knowledge/references/example.config.app-shell.full.md +4 -0
  146. package/dist/knowledge/references/example.provider.backend-module-shape.md +0 -7
  147. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +1 -0
  148. package/dist/knowledge/references/platform.config.saas.md +0 -50
  149. package/dist/knowledge/references/saas.external-data.admin-endpoints.md +48 -0
  150. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +10 -6
  151. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +1 -0
  152. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +0 -109
  153. package/dist/knowledge/references/saas.models.data-mode-read-list.md +0 -137
  154. package/dist/knowledge/references/saas.models.http-api-binding.md +29 -3
  155. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +2 -4
  156. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +0 -2
  157. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +0 -14
  158. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +1 -1
  159. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +0 -36
  160. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +0 -26
  161. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +0 -45
  162. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +1 -1
  163. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +1 -1
  164. package/dist/knowledge/references/zod.decorators.schema-metadata.md +0 -1
  165. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  166. package/dist/knowledge/registries/framework-topics.json +11 -48
  167. package/dist/knowledge/registries/playbooks.json +11 -74
  168. package/dist/knowledge/registries/source-tags.json +538 -622
  169. package/dist/knowledge/skills/INDEX.md +0 -1
  170. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -16
  171. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +8 -26
  172. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +74 -252
  173. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +8 -26
  174. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +21 -36
  175. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +19 -49
  176. package/dist/knowledge/skills/config-app-shell/SKILL.md +8 -6
  177. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +11 -6
  178. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +0 -50
  179. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +0 -7
  180. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +0 -36
  181. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +0 -36
  182. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +0 -36
  183. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +0 -109
  184. package/dist/knowledge/skills/resource-add-resource/SKILL.md +1 -2
  185. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +2 -4
  186. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +0 -2
  187. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +2 -157
  188. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +0 -109
  189. package/dist/knowledge/skills/resource-external-data/SKILL.md +2 -0
  190. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +29 -3
  191. package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +70 -0
  192. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +0 -1
  193. package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +0 -17
  194. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +0 -46
  195. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +0 -26
  196. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +1 -1
  197. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +0 -109
  198. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +1 -1
  199. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +0 -36
  200. package/dist/knowledge/topic-index.json +128 -285
  201. package/dist/tsconfig.build.tsbuildinfo +1 -1
  202. package/dist/tsconfig.tsbuildinfo +1 -1
  203. package/package.json +4 -4
  204. package/dist/esm/.builder.pid +0 -9
  205. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +0 -185
  206. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +0 -66
  207. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +0 -56
  208. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +0 -40
  209. package/dist/knowledge/playbooks/top_down.market-research/method.md +0 -68
  210. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +0 -42
  211. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +0 -239
  212. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +0 -69
  213. package/dist/knowledge/references/placement-plan.config.md +0 -330
  214. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +0 -58
  215. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +0 -118
  216. package/dist/knowledge/references/zod.decorators.data-categories.md +0 -197
  217. package/dist/knowledge/rules/resource-schema-awareness.md +0 -77
  218. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +0 -622
  219. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +0 -245
  220. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +0 -134
  221. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +0 -65
  222. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +0 -127
  223. /package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/structured-artifact-action.json +0 -0
@@ -1,622 +0,0 @@
1
- # Framework Personal-Data Declaration API
2
-
3
- Read this **once per resource**, before you consider it finished.
4
-
5
- It answers one question: **do this resource's rows describe a person?** Every resource owes an
6
- answer — including "no", which is a real answer and has a way to say it.
7
-
8
- ## Why you are asked, when nothing forces you
9
-
10
- The framework does NOT refuse to start a resource that says nothing. That was decided deliberately:
11
- a hard constraint on every author, for every resource, forever is too strict, and the framework's
12
- own directive is that the system works first and protection arrives as guidance rather than as a
13
- refusal wired into the mechanism.
14
-
15
- What happens instead is that the application logs a startup **warning** naming every resource of
16
- yours that has said nothing, and the application's generated privacy notice can say nothing about
17
- those resources. The measured consequence, in a real application: a notice that is accurate about
18
- the platform — identity, credentials, sessions, membership all come free with the engine — and
19
- silent about the contacts, deals and interaction history, which is the data the customers of that
20
- application actually care about.
21
-
22
- So this is the cheapest possible moment to answer. Later means editing a shipped schema.
23
-
24
- ## Four ways to answer, and they are four different questions
25
-
26
- Declaring ANY of them counts as having answered. Declare the ones that are true.
27
-
28
- | declaration | where | the question it answers |
29
- |---|---|---|
30
- | `retentionPolicy` | `resources-config` | does an erasure KEEP this row, and are its fields scrubbed? |
31
- | `dataSubjectPolicy` | `resources-config` | whose LOGIN SESSION does erasing this row end? |
32
- | `systemAccessPolicy.exportSubject` | `resources-config` | do these rows belong in a subject's export bundle? |
33
- | `.dataCategories(...)` | the schema, per field | what KIND of personal data does this field hold? |
34
-
35
- ### The "no personal data" answer is `RETAIN_ONLY`
36
-
37
- `retentionPolicy: { mode: ErasureRetentionMode.RETAIN_ONLY }` means *this resource holds no personal
38
- data of its own*, and it is CHECKED: the resource factory refuses a `.impersonalizeWith()` treatment
39
- beside it, because the treatment would never run. It is a positive statement a compliance document
40
- can cite, not silence — which is exactly why saying it is worth a line.
41
-
42
- A resource that genuinely holds nothing about people — a product catalog, a price list, a pipeline
43
- stage — should say so this way.
44
-
45
- ### The two config declarations that must travel together
46
-
47
- `retentionPolicy` REQUIRES `dataSubjectPolicy`, and `dataSubjectPolicy` is rejected without a
48
- `retentionPolicy`. A retention-governed resource is exactly one that can be handed to an erasure as a
49
- subject, so it must say whether its rows ARE a person and, if so, which field names the user whose
50
- session the erasure ends.
51
-
52
- ⚠️ `dataSubjectPolicy.kind = NO_PRINCIPAL` is the SESSION axis and nothing else. It is equally true
53
- of an invoice and of a CRM contact who has no account. It does NOT mean "not a person" — read
54
- `retentionPolicy.mode` for that.
55
-
56
- ### `.dataCategories()` is per FIELD, and is not derived from names
57
-
58
- A resource-level category cannot express that one row holds a name, an email and a payment token,
59
- which is exactly what a privacy notice enumerates. Nothing in the framework infers a category from a
60
- field's NAME — `email`, `phone` and `dateOfBirth` are suggestive while `notes` is not, and an
61
- inventory built that way is a guess whose misses are silently undisclosed.
62
-
63
- The one category the framework derives is `CREDENTIALS`, from `.isPassword()` / `.isOtp()` /
64
- `.isWriteOnlySecret()` — markers you wrote.
65
-
66
- If you declare `.impersonalizeWith()` on a field, declare a category on it too. A field that is
67
- personal by one declaration and uncategorized by another is reported BY NAME as an outstanding gap
68
- in every compliance document the application produces.
69
-
70
- ## Resource configuration surface
71
-
72
- ## Import Origins
73
-
74
- - `@wildo-ai/saas-models`
75
-
76
- ## Source Excerpts
77
-
78
- ### Origin Package: `@wildo-ai/saas-models`
79
-
80
- ```typescript
81
- *
82
- * Valid operation keys from core + custom enums, and builder params for `createResourceConfiguration`.
83
- */
84
- // Helper type to extract valid operation keys, excluding undefined
85
- export type ValidOperationKeys<
86
- TCustomOperationEnum extends EnumLikeType | undefined,
87
- TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined
88
- > = (TCustomOperationEnum extends EnumLikeType ? EnumValues<TCustomOperationEnum> : never) |
89
- (TCoreOperationEnum extends Partial<CoreResourceOperation> ? TCoreOperationEnum : never);
90
-
91
- /**
92
- *
93
- * Access mode for the ACL-bypassing system-context reads
94
- * (`SystemAccessBackendService.readAsSystem` / `listAsSystem`, from
95
- * `@wildo-ai/saas-backend-lib`).
96
- *
97
- * Those primitives run with a synthesised super-admin execution context and
98
- * therefore SKIP the caller's scope and role checks entirely. A resource is
99
- * readable that way ONLY if its resource configuration opts the verb in. Any
100
- * verb left undeclared defaults to `FORBIDDEN`: a system read of a resource
101
- * that has not opted in throws `ErrorType.CONFIGURATION` — the framework is
102
- * fail-closed here by construction.
103
- */
104
- export enum ResourceSystemAccessMode {
105
- /** The verb's system-context primitive is rejected for this resource (default). */
106
- FORBIDDEN = 'FORBIDDEN',
107
- /** The verb's system-context primitive is permitted for this resource. */
108
- ALLOWED = 'ALLOWED',
109
- }
110
-
111
- /**
112
- * Per-resource opt-in policy for the ACL-bypassing system-context primitives
113
- * on `SystemAccessBackendService`: the reads (`readAsSystem` / `listAsSystem`)
114
- * and the trusted writes (`createAsSystem` / `updateAsSystem` /
115
- * `updateManyAsSystem`).
116
- *
117
- * A system-context call does not REMOVE the authorization decision — it
118
- * RELOCATES it from the resource ACL onto the calling service, which MUST
119
- * enforce an explicit alternative check (e.g. consumable-token or
120
- * email-ownership matching). Declaring this policy is the data owner's
121
- * statement that such a bypass is permissible at all, and for which verb. An
122
- * absent policy — or a verb set to (or left defaulting to) `FORBIDDEN` — makes
123
- * the primitive throw.
124
- *
125
- * The WRITE verbs additionally let a trusted in-process caller persist the
126
- * fields the client-shaped request DTO strips — `.isBackendOnly()` material
127
- * (e.g. a credential `passwordHash`) and the context-auto-populated FKs (e.g.
128
- * `userId` on a system resource that has no HTTP surface to seed it) — by
129
- * re-attaching exactly those fields after the strict parse. They are the
130
- * sanctioned path for engine flows like registration that must write system
131
- * resources directly; opting a verb in is the data owner's acknowledgement that
132
- * a super-admin-context mutation of this resource is legitimate.
133
- *
134
- * Caveats a system-context call inherits (it runs as super-admin), to weigh
135
- * before opting in:
136
- * - a READ returns the FULL record — every field, including ones a normal
137
- * caller's role / field-visibility would hide — so never forward the result
138
- * verbatim to an under-privileged caller; project only what is safe.
139
- * - a WRITE bypasses the caller's scope + role ACL, so the calling service
140
- * owns the authorization decision (only trusted engine code can reach the
141
- * primitive — it is never exposed to an HTTP payload).
142
- * - feature flags do not gate it (it is an internal request).
143
- * - the policy is RESOURCE-LEVEL: for a polymorphic resource it is shared by
144
- * every scope variant (declare it once on the shared config).
145
- *
146
- * Intentionally DISTINCT from `isSystemResource`: marking a resource as
147
- * framework infrastructure does NOT imply that an ACL bypass is acceptable
148
- * for its data. Keep the two concepts separate.
149
- */
150
- export type ResourceSystemAccessPolicy = {
151
- /** Governs `readAsSystem`. Omitted ⇒ FORBIDDEN. */
152
- read?: ResourceSystemAccessMode,
153
- /** Governs `listAsSystem`. Omitted ⇒ FORBIDDEN. */
154
- list?: ResourceSystemAccessMode,
155
- /** Governs `createAsSystem`. Omitted ⇒ FORBIDDEN. */
156
- create?: ResourceSystemAccessMode,
157
- /** Governs `updateAsSystem`. Omitted ⇒ FORBIDDEN. */
158
- update?: ResourceSystemAccessMode,
159
- /** Governs `updateManyAsSystem`. Omitted ⇒ FORBIDDEN. */
160
- updateMany?: ResourceSystemAccessMode,
161
- // NOTE: there is deliberately NO `delete` verb here — there is no `deleteAsSystem` primitive. A row is
162
- // removed either through its own DELETE operation ACL (e.g. an owner-facing `API_CALL` DELETE under the
163
- // USER_SELF owner filter) or by the `onParentDelete` composition cascade (which deletes at the raw
164
- // repository layer, variant-agnostic — see `deleteChildrenImmediate`). If you find yourself reaching
165
- // for `systemAccessPolicy.delete`, model the removal as one of those two instead.
166
- /**
167
- * Governs the impersonalization see-through reads (`readRetainedAsSystem` /
168
- * `listRetainedAsSystem`) — the privileged, audited path that reveals
169
- * `retentionStatus = RETAINED` rows hidden-by-default. Omitted ⇒ FORBIDDEN.
170
- * Auto-derived to `ALLOWED` by the factory when a resource opts into
171
- * `retentionPolicy`; never authored by hand in the common case.
172
- *
173
- * **LIVE.** `readRetainedAsSystem` / `listRetainedAsSystem` exist and are enforced: the verb is
174
- * asserted fail-closed, a privileged human role is required, and every reveal emits a
175
- * human-attributed `RETAINED_DATA_ACCESS` audit event. (This block previously said the primitives
176
- * were "wired in a later phase" — false since the M5b work landed.)
177
- */
178
- seeRetained?: ResourceSystemAccessMode,
179
-
180
- /**
181
- * May this resource's rows be swept into a SUBJECT EXPORT bundle (GDPR Art. 15 / Art. 20)?
182
- *
183
- * Fail-closed by omission, like every other verb here. A subject export reads across the whole
184
- * child-direction graph of its subject, so without an explicit opt-in a resource could be
185
- * disclosed to a data subject because it merely sits on an edge — nobody having decided that its
186
- * contents are appropriate to hand over.
187
- *
188
- * **The refusal is LOUD, not a silent skip.** When an edge the classifier marked for inclusion
189
- * belongs to a resource that has not opted in, the export REFUSES and names it. Silently dropping
190
- * it would produce an access bundle that is incomplete without saying so — a disclosure failure
191
- * wearing the appearance of a successful response, which is the same class of lie as the routed
192
- * export operations this capability replaced. Refusing is a one-line fix per resource; a silent
193
- * omission is undetectable.
194
- *
195
- * NOT derived from `portabilityPolicy`: declaring where fields came from (Art. 20 scoping) and
196
- * consenting to be disclosed at all are different decisions, and a resource may legitimately want
197
- * the first without the second.
198
- */
199
- exportSubject?: ResourceSystemAccessMode,
200
- };
201
-
202
- /**
203
- * Resource-level opt-in to the **impersonalization-on-erasure** capability: on erasure the
204
- * resource is impersonalized-and-retained (personal fields scrubbed, row kept for a legal/audit
205
- * obligation) instead of hard-deleted. When set, the factory injects a `retentionStatus` marker
206
- * and derives the `updateMany` + `seeRetained` system-access grants.
207
- *
208
- * RESOURCE-level (intrinsic, trigger-agnostic). The per-EDGE trigger is
209
- * `onParentDelete.strategy = IMPERSONALIZE_AND_RETAIN`; the per-FIELD scrub is `.impersonalizeWith()`.
210
- *
211
- * **LIVE — opting in has real effect today.** The marker + derived grants, the in-place scrub writer,
212
- * the `IMPERSONALIZE_AND_RETAIN` cascade mode and the hidden-by-default read filter all exist and are
213
- * enforced. A RETAINED row is invisible to reads, lists, counts and CHART aggregates, and immutable
214
- * to ordinary writes, on BOTH persistence adapters; the only door is the audited see-through path.
215
- *
216
- * Runtime-proven, not asserted — and scoped precisely, because an earlier revision of this block
217
- * over-claimed it. Against a real MongoDB, the erasure orchestrator reaches its terminal path and its
218
- * receipt is truthful over a registered subset of resources
219
- * (`subject-erasure-completion.mongo.integration.test.ts`); the retention OUTCOME and a SECOND erasure
220
- * are observed (`subject-impersonalization-retention-outcome.mongo.integration.test.ts`); and a
221
- * retained row is absent from a real application chart over real HTTP
222
- * (Your Application `e2e/chart-retention-hide.e2e.ts`).
223
- *
224
- * What is NOT proven: that an erasure completes over the FULL `onParentDelete` closure, and that
225
- * external (provider-side) effects run. The completion lane deliberately requires
226
- * `declinedEdges.length > 0`, so it asserts a state in which some edges were NOT executed, and
227
- * `externalEffects` is stubbed empty. Do not read "runtime-proven" here as end-to-end completeness.
228
- *
229
- * (This block previously read "Contract only in this phase … No record is impersonalized-and-retained
230
- * yet." That was true when written and became false without being revisited — it is the public
231
- * authoring contract an app developer reads before declaring this policy, so it is corrected here
232
- * rather than left to mislead.)
233
- *
234
- * ⚠️ NOT the anonymous-user concept (`isAnonymizable` is pre-auth ownership transposition — the
235
- * opposite direction). Reuse of that mechanism, never its name.
236
- */
237
- /**
238
- * WHO a row of this resource is with respect to an erasure, and where that person's session lives.
239
- * The companion of {@link ResourceRetentionPolicy}: retention says what happens to the ROW and whether
240
- * the row holds personal data at all; this says **whose SESSION an erasure of it must end**.
241
- *
242
- * The two are independent, and reading this one as "is the row about a person" is the mistake that
243
- * cost `NO_PRINCIPAL` its previous name — see {@link ResourceDataSubjectKind}. A CRM contact holds
244
- * personal data (`RETAIN_AND_IMPERSONALIZE`) and has no session (`NO_PRINCIPAL`); an invoice holds
245
- * none (`RETAIN_ONLY`) and also has no session. Same value here, opposite compliance meaning, and the
246
- * retention mode is what tells them apart.
247
- *
248
- * Required on every resource declaring a {@link ResourceRetentionPolicy}, because those are exactly
249
- * the resources that can be passed to `eraseSubjectAsSystem` as a subject (the orchestrator refuses a
250
- * subject with no retention policy). Undeclared fails at config build rather than defaulting: the safe
251
- * default is unknowable — guessing `NO_PRINCIPAL` silently drops a real person's revocation, and
252
- * guessing a linked principal revokes the wrong people. See {@link ResourceDataSubjectKind} for why
253
- * the linkage can never be inferred from the presence of a user foreign key.
254
- */
255
- export interface ResourceDataSubjectPolicy {
256
- /** Whose login session an erasure of this row must end — never whether the row is about a person. */
257
- kind: ResourceDataSubjectKind;
258
- /**
259
- * The field naming the `USERS` row whose session an erasure of this row must end.
260
- *
261
- * REQUIRED when {@link kind} is `LINKED_PRINCIPAL`, and FORBIDDEN otherwise — under
262
- * `SELF_PRINCIPAL` the row's own id is the principal, and under `NO_PRINCIPAL` there is no
263
- * principal at all, so a field there would be a contradiction rather than redundancy. Both
264
- * directions are enforced at config build.
265
- */
266
- sessionPrincipalField?: string;
267
- }
268
-
269
- export interface ResourceRetentionPolicy {
270
- /**
271
- * WHAT happens to a row of this resource when its subject is erased.
272
- *
273
- * Both modes retain the row (kept, marked `RETAINED`, hidden from normal reads and immutable,
274
- * readable only through the audited see-through path). They differ on whether the row's own FIELDS
275
- * additionally need scrubbing — which is a genuinely separate question, because a record can be
276
- * legally retainable while holding no personal data of its own (a financial row that merely POINTS
277
- * at a person). Fusing the two forced such a resource to either invent a fake scrub or forgo
278
- * retention entirely; keeping them distinct is what makes "retain, nothing to scrub" expressible.
279
- */
280
- mode: ErasureRetentionMode;
281
- }
282
-
283
- /**
284
- * Resource-level DEFAULT for where this resource's field values came from — the axis that decides
285
- * GDPR Art. 20 (portability) scope. Per-field overrides are `.portabilityProvenance()`.
286
- *
287
- * ## Why a resource-level default exists at all
288
- *
289
- * Art. 20 is intrinsically a per-FIELD question: one row routinely mixes data the subject supplied
290
- * (`firstName`) with data the controller produced about them (a computed score, a server-assigned
291
- * status). But requiring a decorator on EVERY field of every resource would make the capability
292
- * unadoptable, and an unadopted disclosure capability is worse than a coarse one — it means
293
- * portability requests cannot be answered at all.
294
- *
295
- * So the declaration is two-level: this default carries the resource's common case in one line, and
296
- * only fields that DIFFER from it need a decorator. A `USER_PROFILES` resource is
297
- * `SUBJECT_PROVIDED` by default with a handful of derived exceptions; an `AUDIT_LOGS` resource is
298
- * `DERIVED` throughout with none.
299
- *
300
- * ## Why it is optional, and what happens without it
301
- *
302
- * Omitting it entirely is legitimate: **Art. 15 (access) never consults provenance**, so an
303
- * application can answer access requests in full before annotating anything. Only an Art. 20
304
- * portability export needs the axis, and for a resource where neither the field nor this default
305
- * declares one, that export REFUSES rather than guessing — see
306
- * `SubjectExportFieldScope.UNDECLARED` for why neither guess is the safe one.
307
- *
308
- * ⚠️ NOT `retentionPolicy`. That says what happens to a value on ERASURE (destroy vs retain-and-
309
- * scrub); this says where the value ORIGINATED, for a DISCLOSURE decision. A field is commonly
310
- * `SUBJECT_PROVIDED` here and masked on erasure there — orthogonal axes on the same value.
311
- */
312
- export interface ResourcePortabilityPolicy {
313
- /**
314
- * The provenance every field of this resource is assumed to carry unless its own
315
- * `.portabilityProvenance()` says otherwise.
316
- */
317
- defaultProvenance: DataPortabilityProvenance;
318
- }
319
-
320
- /**
321
- * Builder parameters for creating a resource configuration.
322
- * NOTE: databaseSchema has been removed. Backend-only fields are now marked with
323
- * the isBackendOnly decorator in mainSchema and are stripped at the service layer.
324
- */
325
- export type ResourceConfiguration_BuilderParameters<
326
- TCustomOperationEnum extends EnumLikeType | undefined,
327
- TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined,
328
- TMainSchema extends z.ZodTypeAny,
329
- > = {
330
- isDisabled?: boolean, // default false
331
- mainSchema: TMainSchema,
332
- resourceIdentifier : ResourceType,
333
- resourceFieldIdentifier : ResourceFieldIdentifier,
334
- resourceRelationships : ResourceRelationship[],
335
- inheritenceSchemaDefinition?: ResourceConfiguration_InheritanceSchemaDefinition<EnumLikeType,TMainSchema>,
336
-
337
- /**
338
- * Persistence adapter (database type) for this resource.
339
- * - `mongodb`: MongoDB with Mongoose ORM
340
- * - `postgresql`: PostgreSQL (SQL adapter)
341
- *
342
- * If not specified, uses `appConfig.database.defaultAdapter` — which is the normal case and
343
- * should stay the normal case.
344
- *
345
- * **Declaring a value that DISAGREES with the application default is refused at registration
346
- * unless {@link ResourceConfiguration_BuilderParameters.persistenceAdapterIsolation} is also
347
- * declared.** An application is wholly one adapter by default because two adapters cannot
348
- * share a native transaction; the isolation declaration is the only way past that refusal,
349
- * and it is a claim about this resource's write topology rather than a way to silence the
350
- * error. Declaring an adapter that AGREES with the default is always fine and needs nothing.
351
- */
352
- persistenceAdapter?: PersistenceAdapterType,
353
-
354
- /**
355
- * This resource's declared relationship to cross-adapter atomic write boundaries.
356
- *
357
- * Required — and only meaningful — when {@link
358
- * ResourceConfiguration_BuilderParameters.persistenceAdapter} disagrees with
359
- * `appConfig.database.defaultAdapter`. Without it, the resources registry refuses the
360
- * application at startup; with it, the registry admits the resource and LOGS the admitted
361
- * set, so a mixed configuration is always named and never ambient.
362
- *
363
- * Read {@link ResourcePersistenceAdapterIsolation} before declaring one: the member is an
364
- * assertion about the resource's design that the persistence unit of work will still enforce
365
- * at every real boundary.
366
- */
367
- persistenceAdapterIsolation?: ResourcePersistenceAdapterIsolationType,
368
-
369
- /**
370
- * REQUIRED companion declaration when `persistenceAdapter` is `HTTP_API`; forbidden otherwise.
371
- *
372
- * Carries everything the external repository needs that the platform does not own: provider
373
- * reference (credentials resolve through `ExternalProvidersRegistryBackendService`), transport
374
- * dialect, remote entity, ordered key declaration (id synthesis), identity mode, tenancy
375
- * stance, erasure stance, and remote-call semantics. The factory enforces presence/absence
376
- * coherence and content-validates the declaration.
377
- */
378
- httpApiBinding?: HttpApiResourceBinding,
379
- /** REQUIRED when `persistenceAdapter` is INTROSPECTION; meaningless otherwise. */
380
- introspectionBinding?: IntrospectionResourceBinding,
381
-
382
- /**
383
- * OPTIONAL inbound ETL pipeline on an ordinary LOCAL resource — "some resources local, some
384
- * remote, ETL between them" (partial-resource coverage, model v3; PR-3). FORBIDDEN on an
385
- * HTTP_API-adapter resource: a virtual resource IS the remote side. The factory
386
- * content-validates the declaration and every mainSchema-dependent coherence rule (the
387
- * remote-key field is a declared `.isBusinessKey()` + excludeFromCreate/Update STRING; mapped
388
- * targets exist, accept null unless `required`, and are excludeFromCreate/Update; CLOSED
389
- * population refuses caller CREATE operations).
390
- */
391
- externalDataPipeline?: ExternalDataPipelineDeclaration,
392
-
393
- isSystemResource?: boolean, // default false - true for core system resources (organizations, users, etc.), false for tenant-specific resources
394
-
395
- /**
396
- * Does this resource's OWN primary-key URL segment name the CALLER, or the SUBJECT?
397
- *
398
- * Default `true` (the segment names the caller) — deliberately the SAFE default, so a resource
399
- * whose author has not considered the question keeps the identity-coherence guard rather than
400
- * silently losing it.
401
- *
402
- * ## Why this cannot be inferred
403
- *
404
- * The W3.6 identity-coherence guard (`handleUserJwtAuthentication` →
405
- * `AUTHORIZATION_USER_ID_MISMATCH`) refuses a request whose URL `userId` differs from the JWT
406
- * subject. That is exactly right for `USER_SELF` (`/user-self/{userId}` — the segment IS the
407
- * caller, pinned by the horizontal-IDOR probes) and for child routes under a user
408
- * (`/users/{userId}/draft-notes` — a PARENT segment naming whose rows these are).
409
- *
410
- * It is exactly WRONG for `USERS`, whose own `resourceFieldIdentifier` is also `userId` but whose
411
- * segment names the TARGET of an administrative action. Both resources are keyed on the same
412
- * field name, so no structural rule can tell them apart — the framework already had to add
413
- * `coreResourceShared_FieldIdentifierPriority` to disambiguate the very same collision for FK
414
- * resolution. This declaration is that disambiguation for IDENTITY.
415
- *
416
- * ## What it does and does not change
417
- *
418
- * Setting `false` relaxes ONLY the coherence refusal. It does not touch:
419
- * - `initiatorIds.userId`, which is taken from the JWT and spread LAST precisely so a URL can
420
- * never spoof the caller (see the `W3.6` comment at that assignment) — so permitting the
421
- * mismatch cannot produce impersonation;
422
- * - the contextual-field map, which legitimately carries the ADDRESSED resource's id;
423
- * - authorization, which still decides whether this caller may run this operation at all.
424
- *
425
- * Set `false` only for an administrative resource whose primary key is a person/tenant identifier
426
- * that a privileged caller is MEANT to address on someone else's behalf.
427
- */
428
- primaryKeyIdentifiesInitiator?: boolean,
429
-
430
- /**
431
- * Opt-in policy for the ACL-bypassing system-context primitives
432
- * (`readAsSystem` / `listAsSystem` and the trusted writes `createAsSystem` /
433
- * `updateAsSystem` / `updateManyAsSystem`). Omitted ⇒ EVERY verb FORBIDDEN
434
- * (fail-closed): a system-context call on this resource throws unless the
435
- * matching verb is explicitly set to ALLOWED. Declare ONLY the verb(s) that
436
- * genuinely need a system bypass, and ensure the calling service enforces an
437
- * explicit alternative authorization.
438
- */
439
- systemAccessPolicy?: ResourceSystemAccessPolicy,
440
- coreOperations: TCoreOperationEnum[],
441
- customOperation?: TCustomOperationEnum, // default undefined
442
- operationsConfiguration : { [K in ValidOperationKeys<TCustomOperationEnum, TCoreOperationEnum>]: OperationConfig_ForKey<K, TMainSchema> }
443
- /**
444
- * Configuration for auto-generated operation variants.
445
- * Controls which READ/LIST variants (summary, context) are auto-generated.
446
- * All variants are enabled by default.
447
- */
448
- autoVariants?: ResourceConfiguration_AutoVariants,
449
- // NOTE: responseSummaryDto removed - now auto-derived from isSummaryField() decorators in factory
450
-
451
- /**
452
- * W7.3a: Marks this resource as accessible to anonymous sessions.
453
- * When true, the factory auto-generates dual URL paths (USER_SELF + ANONYMOUS)
454
- * and a STANDALONE relationship to ANONYMOUS_USERS.
455
- * The resource MUST have a nullable `userId` field.
456
- */
457
- isAnonymizable?: boolean,
458
-
459
- /**
460
- * W7.3a: Controls how anonymous resources are handled during transposition.
461
- * Only meaningful when isAnonymizable is true.
462
- * Defaults to ADD (simple ownership reassignment).
463
- */
464
- transpositionPolicy?: ResourceTranspositionPolicy,
465
-
466
- /**
467
- * Opt in to impersonalization-on-erasure (retain + scrub instead of hard-delete). When set, the
468
- * factory injects a `retentionStatus` marker and derives the `updateMany` / `seeRetained`
469
- * system-access grants. Per-field scrub is `.impersonalizeWith()`; the per-edge trigger is the
470
- * `IMPERSONALIZE_AND_RETAIN` cascade mode.
471
- *
472
- * **LIVE.** Marker injection, grant derivation, the scrub writer, the cascade mode and the
473
- * hidden-by-default read filter are all enforced today — see `ResourceRetentionPolicy` for the
474
- * runtime evidence. Declaring this changes behaviour; it is not a forward declaration.
475
- *
476
- * Declaring this also REQUIRES {@link dataSubjectPolicy}: a retention-governed resource is exactly
477
- * one that can be handed to `eraseSubjectAsSystem` as a subject, so it must say whether its rows are
478
- * a person — and if so, whose session an erasure ends.
479
- */
480
- retentionPolicy?: ResourceRetentionPolicy,
481
-
482
- /**
483
- * WHO a row of this resource is with respect to an erasure — and, when it is a person, which field
484
- * names the `USERS` row whose session that erasure must end.
485
- *
486
- * Mandatory for any resource declaring a {@link retentionPolicy}; meaningless (and rejected) without
487
- * one, since a resource with no retention policy can never be an erasure subject. See
488
- * {@link ResourceDataSubjectPolicy}.
489
- */
490
- dataSubjectPolicy?: ResourceDataSubjectPolicy,
491
-
492
- /**
493
- * Resource-level DEFAULT provenance for GDPR Art. 20 (portability) scoping; per-field overrides
494
- * are `.portabilityProvenance()`. Optional — Art. 15 (access) never consults provenance, so an
495
- * application can answer access requests without declaring this. See
496
- * {@link ResourcePortabilityPolicy}.
497
- */
498
- portabilityPolicy?: ResourcePortabilityPolicy,
499
- }
500
- ```
501
-
502
- ## System-access policy (where `exportSubject` lives)
503
-
504
- ## Import Origins
505
-
506
- - `@wildo-ai/saas-models`
507
-
508
- ## Source Excerpts
509
-
510
- ### Origin Package: `@wildo-ai/saas-models`
511
-
512
- ```typescript
513
- *
514
- * Access mode for the ACL-bypassing system-context reads
515
- * (`SystemAccessBackendService.readAsSystem` / `listAsSystem`, from
516
- * `@wildo-ai/saas-backend-lib`).
517
- *
518
- * Those primitives run with a synthesised super-admin execution context and
519
- * therefore SKIP the caller's scope and role checks entirely. A resource is
520
- * readable that way ONLY if its resource configuration opts the verb in. Any
521
- * verb left undeclared defaults to `FORBIDDEN`: a system read of a resource
522
- * that has not opted in throws `ErrorType.CONFIGURATION` — the framework is
523
- * fail-closed here by construction.
524
- */
525
- export enum ResourceSystemAccessMode {
526
- /** The verb's system-context primitive is rejected for this resource (default). */
527
- FORBIDDEN = 'FORBIDDEN',
528
- /** The verb's system-context primitive is permitted for this resource. */
529
- ALLOWED = 'ALLOWED',
530
- }
531
-
532
- /**
533
- * Per-resource opt-in policy for the ACL-bypassing system-context primitives
534
- * on `SystemAccessBackendService`: the reads (`readAsSystem` / `listAsSystem`)
535
- * and the trusted writes (`createAsSystem` / `updateAsSystem` /
536
- * `updateManyAsSystem`).
537
- *
538
- * A system-context call does not REMOVE the authorization decision — it
539
- * RELOCATES it from the resource ACL onto the calling service, which MUST
540
- * enforce an explicit alternative check (e.g. consumable-token or
541
- * email-ownership matching). Declaring this policy is the data owner's
542
- * statement that such a bypass is permissible at all, and for which verb. An
543
- * absent policy — or a verb set to (or left defaulting to) `FORBIDDEN` — makes
544
- * the primitive throw.
545
- *
546
- * The WRITE verbs additionally let a trusted in-process caller persist the
547
- * fields the client-shaped request DTO strips — `.isBackendOnly()` material
548
- * (e.g. a credential `passwordHash`) and the context-auto-populated FKs (e.g.
549
- * `userId` on a system resource that has no HTTP surface to seed it) — by
550
- * re-attaching exactly those fields after the strict parse. They are the
551
- * sanctioned path for engine flows like registration that must write system
552
- * resources directly; opting a verb in is the data owner's acknowledgement that
553
- * a super-admin-context mutation of this resource is legitimate.
554
- *
555
- * Caveats a system-context call inherits (it runs as super-admin), to weigh
556
- * before opting in:
557
- * - a READ returns the FULL record — every field, including ones a normal
558
- * caller's role / field-visibility would hide — so never forward the result
559
- * verbatim to an under-privileged caller; project only what is safe.
560
- * - a WRITE bypasses the caller's scope + role ACL, so the calling service
561
- * owns the authorization decision (only trusted engine code can reach the
562
- * primitive — it is never exposed to an HTTP payload).
563
- * - feature flags do not gate it (it is an internal request).
564
- * - the policy is RESOURCE-LEVEL: for a polymorphic resource it is shared by
565
- * every scope variant (declare it once on the shared config).
566
- *
567
- * Intentionally DISTINCT from `isSystemResource`: marking a resource as
568
- * framework infrastructure does NOT imply that an ACL bypass is acceptable
569
- * for its data. Keep the two concepts separate.
570
- */
571
- export type ResourceSystemAccessPolicy = {
572
- /** Governs `readAsSystem`. Omitted ⇒ FORBIDDEN. */
573
- read?: ResourceSystemAccessMode,
574
- /** Governs `listAsSystem`. Omitted ⇒ FORBIDDEN. */
575
- list?: ResourceSystemAccessMode,
576
- /** Governs `createAsSystem`. Omitted ⇒ FORBIDDEN. */
577
- create?: ResourceSystemAccessMode,
578
- /** Governs `updateAsSystem`. Omitted ⇒ FORBIDDEN. */
579
- update?: ResourceSystemAccessMode,
580
- /** Governs `updateManyAsSystem`. Omitted ⇒ FORBIDDEN. */
581
- updateMany?: ResourceSystemAccessMode,
582
- // NOTE: there is deliberately NO `delete` verb here — there is no `deleteAsSystem` primitive. A row is
583
- // removed either through its own DELETE operation ACL (e.g. an owner-facing `API_CALL` DELETE under the
584
- // USER_SELF owner filter) or by the `onParentDelete` composition cascade (which deletes at the raw
585
- // repository layer, variant-agnostic — see `deleteChildrenImmediate`). If you find yourself reaching
586
- // for `systemAccessPolicy.delete`, model the removal as one of those two instead.
587
- /**
588
- * Governs the impersonalization see-through reads (`readRetainedAsSystem` /
589
- * `listRetainedAsSystem`) — the privileged, audited path that reveals
590
- * `retentionStatus = RETAINED` rows hidden-by-default. Omitted ⇒ FORBIDDEN.
591
- * Auto-derived to `ALLOWED` by the factory when a resource opts into
592
- * `retentionPolicy`; never authored by hand in the common case.
593
- *
594
- * **LIVE.** `readRetainedAsSystem` / `listRetainedAsSystem` exist and are enforced: the verb is
595
- * asserted fail-closed, a privileged human role is required, and every reveal emits a
596
- * human-attributed `RETAINED_DATA_ACCESS` audit event. (This block previously said the primitives
597
- * were "wired in a later phase" — false since the M5b work landed.)
598
- */
599
- seeRetained?: ResourceSystemAccessMode,
600
-
601
- /**
602
- * May this resource's rows be swept into a SUBJECT EXPORT bundle (GDPR Art. 15 / Art. 20)?
603
- *
604
- * Fail-closed by omission, like every other verb here. A subject export reads across the whole
605
- * child-direction graph of its subject, so without an explicit opt-in a resource could be
606
- * disclosed to a data subject because it merely sits on an edge — nobody having decided that its
607
- * contents are appropriate to hand over.
608
- *
609
- * **The refusal is LOUD, not a silent skip.** When an edge the classifier marked for inclusion
610
- * belongs to a resource that has not opted in, the export REFUSES and names it. Silently dropping
611
- * it would produce an access bundle that is incomplete without saying so — a disclosure failure
612
- * wearing the appearance of a successful response, which is the same class of lie as the routed
613
- * export operations this capability replaced. Refusing is a one-line fix per resource; a silent
614
- * omission is undetectable.
615
- *
616
- * NOT derived from `portabilityPolicy`: declaring where fields came from (Art. 20 scoping) and
617
- * consenting to be disclosed at all are different decisions, and a resource may legitimately want
618
- * the first without the second.
619
- */
620
- exportSubject?: ResourceSystemAccessMode,
621
- };
622
- ```