@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
@@ -292,11 +292,9 @@ fields (derived from the schema, never caller-supplied). Distinct from `isSystem
292
292
  - `references/framework-saas-models-resource-config-api.md` — source-backed `resources-config` / registry types, including transactional token generation, relational `searchableFields`, and `forwardedLabel`
293
293
  - `references/framework-saas-models-operation-scope-enums-api.md` — source-backed operation & scope enums
294
294
  - `references/framework-system-access-reads-api.md` — source-backed `systemAccessPolicy` opt-in + the `SystemAccessBackendService` read AND trusted-write API (ACL-bypassing system-context reads + writes)
295
- - `references/framework-personal-data-declaration-api.md` — **read once per resource**: does it hold data about a person, and the four ways to answer (including the checked way to say "no")
296
295
 
297
296
  ## Verification
298
297
 
299
- - [ ] The resource has ANSWERED the personal-data question — a `retentionPolicy` (`RETAIN_ONLY` is the checked way to say it holds none of its own), a `dataSubjectPolicy`, a `systemAccessPolicy.exportSubject`, or a `.dataCategories()` declaration on the fields that hold it. Startup warns by name for every application resource that has said nothing.
300
298
  - [ ] Every FK in the schema has a matching `createResourcesRelationship(...)` entry in the module relationships file
301
299
  - [ ] Every relationship that resolves to multiple FKs to the same parent type sets `foreignKeyField` explicitly
302
300
  - [ ] Operations referenced from `*.ui-behavior.tsx` exist in `*.resources-config.ts`
@@ -176,147 +176,10 @@ export enum DataMode {
176
176
  *
177
177
  * If not specified at resource level, uses `appConfig.database.defaultAdapter`.
178
178
  */
179
- /**
180
- * What an INTROSPECTION-backed resource projects.
181
- *
182
- * Declared BY THE AUTHOR beside the resource, exactly as `httpApiBinding` is, and for the same
183
- * reason: the adapter answers "how rows are reached", and everything specific to THIS resource's
184
- * reach is a typed declaration rather than runtime inference.
185
- *
186
- * Keeping it here rather than in a companion-side lookup table matters. A table keyed by resource
187
- * type would be a second enumeration of a population the resource configs already define — the
188
- * shape that silently drifts when one side gains an entry.
189
- */
190
- export enum IntrospectionTenancyStance {
191
- /**
192
- * The rows describe the APPLICATION'S OWN STRUCTURE — its modules, resource specifications,
193
- * design system, compliance declarations — and carry no tenant dimension, so there is nothing for
194
- * a contextual scope predicate to filter on.
195
- *
196
- * This is the only stance implemented, and it is declared rather than inferred for the reason
197
- * `HttpApiTenancyStance` gives for its own: an unstated stance is indistinguishable from an
198
- * overlooked one. Every other repository enforces scoping ITSELF — Mongo and PostgreSQL through
199
- * `buildContextualFilter`, HTTP_API through its tenancy stance — so a read-through adapter that
200
- * simply returned whatever its source produced would be the one backing kind with no scoping
201
- * story, and nobody would be asked to notice.
202
- */
203
- APPLICATION_STRUCTURE = 'application-structure',
204
-
205
- /**
206
- * The rows carry a tenant dimension and a scope predicate must be pushed into the source.
207
- *
208
- * REFUSED AT REGISTRATION today: no introspection behavior takes a scope argument, so the engine
209
- * has nothing to push down. Declared as a member rather than omitted so the refusal is explicit
210
- * and a future scoped behavior is a deliberate design step — the alternative is that the first
211
- * author needing it discovers the gap by shipping unscoped rows.
212
- */
213
- SCOPE_FILTER_PUSHDOWN = 'scope-filter-pushdown',
214
- }
215
-
216
- export interface IntrospectionResourceBinding {
217
- /**
218
- * The companion introspection behavior whose output becomes this resource's rows.
219
- *
220
- * A plain string on purpose: the behavior catalog lives in the companion (23 behaviors as of
221
- * 2026-08-29) and the engine must not depend on it. An unknown id is refused by the companion at
222
- * read time, naming the id and the supported set.
223
- */
224
- readonly behavior: string;
225
-
226
- /**
227
- * Path into the behavior's result that holds the rows, dot-separated. Omitted means the result
228
- * itself is the row collection.
229
- *
230
- * Behaviors answer their own natural shape — `{ frontendChartRegistrationRefs: [...] }` — and
231
- * teaching each one to answer a uniform envelope would change 23 working behaviors to suit a
232
- * consumer that arrived later.
233
- */
234
- readonly rowsPath?: string;
235
-
236
- /**
237
- * REQUIRED. Why these rows need no contextual scope predicate, or that they do.
238
- *
239
- * Not optional and not defaulted: a default would make "nobody thought about tenancy" and
240
- * "tenancy does not apply here" the same declaration.
241
- */
242
- readonly tenancy: IntrospectionTenancyStance;
243
-
244
- /**
245
- * Fields whose values COMPOSE each row's primary key, in order, when the behavior's rows carry no
246
- * identifier of their own.
247
- *
248
- * Most introspection behaviors answer structural projections rather than records: a module row
249
- * carries `moduleId` and needs nothing here, while a relationship row carries only the two
250
- * resource types it joins. Without a key such a resource can be LISTed and never READ, because
251
- * there is no value to address a row by.
252
- *
253
- * Composition is DECLARED rather than derived because only the author knows which fields are
254
- * jointly unique for a given behavior — and being wrong is not hypothetical. `resourceType1` +
255
- * `resourceType2` is unique across all 16 relationships in the dogfood application and is still
256
- * unsafe in general, since the framework permits several edges between the same pair (a junction
257
- * with two roles, a self-relationship). So the source FAILS LOUDLY when two rows compose the same
258
- * key rather than serving both under one id, which would make READ return an arbitrary one of
259
- * them and give no sign anything was wrong.
260
- *
261
- * The composed value is written to the resource's own `resourceFieldIdentifier`, which is the one
262
- * key name resolvable from the registry without introspecting the schema's decorators. A resource
263
- * declaring `identityFields` must therefore name that field as its primary key.
264
- *
265
- * The values are joined verbatim, so the key stays READABLE — `workspace__users__createdByUserId`
266
- * rather than an opaque hash. That is possible because an INTROSPECTION-backed resource resolves
267
- * to `ResourceIdFormat.INTROSPECTION_SYNTHESIZED`, which admits a URL-safe charset instead of the
268
- * ObjectId-or-UUID rule platform rows follow.
269
- *
270
- * It was briefly a deterministic UUIDv5, before that format existed. Hashing worked and was the
271
- * wrong trade: it made every id opaque, and it disguised the real property — a DERIVED id is only
272
- * as stable as the fields it is derived from, and hiding that behind a hash removes the reader's
273
- * ability to notice when a row's identity moves.
274
- *
275
- * Each value must be URL-safe (`[a-zA-Z0-9_-]`) and the whole key at most 255 characters; the
276
- * source refuses per row rather than emitting a key that lists and cannot be read.
277
- *
278
- * Omit when the behavior's rows already carry an identifier of their own.
279
- */
280
- readonly identityFields?: readonly string[];
281
- }
282
-
283
179
  export enum PersistenceAdapter {
284
180
  MONGODB = 'mongodb',
285
181
  POSTGRESQL = 'postgresql',
286
182
 
287
- /**
288
- * Rows are DERIVED on demand by asking the running dev companion to introspect the application —
289
- * its resource registry, specifications, design system, compliance facts, assertions, market and
290
- * persona context. Nothing is stored: every read recomputes.
291
- *
292
- * ## Why this is an adapter and not a service call
293
- *
294
- * The companion already computes all of it — 23 named introspection behaviors — and today each is
295
- * reachable only through a bespoke route. Making it an adapter is what turns those behaviors into
296
- * ordinary RESOURCES: list, read, filter, search, labels, navigation, all generated, with no
297
- * per-behavior UI. That is the same argument `HTTP_API` settled on 2026-08-26 — the adapter answers
298
- * "how rows are reached", and the mechanism behind it is a binding an author declares.
299
- *
300
- * Distinct from `HTTP_API`, deliberately, and not merely because the transport differs. Retrieval
301
- * is a SUBPROCESS that imports the target application's built modules; it costs seconds rather than
302
- * milliseconds, it requires that application's `dist` to exist, and its failure mode is a behavior
303
- * throwing rather than a row being absent. Collapsing the two would give one declaration whose
304
- * discriminator chooses between an HTTP call and a subprocess — two adapters wearing one name.
305
- *
306
- * ## What every adapter decision site must honor
307
- *
308
- * - **READ-ONLY, absolutely.** There is no writable target: a row is a projection of the
309
- * application's own source. Every write method refuses, as `HTTP_API`'s twelve do.
310
- * - **No provisioning, migration or schema surface.** Nothing is stored, so there is nothing to
311
- * create, migrate or verify — the platform must never believe it owns a store here.
312
- * - **Never a legal application-wide DEFAULT adapter.** It is a per-resource declaration only;
313
- * an application whose default was introspection could persist nothing at all.
314
- * - **It must DEGRADE, never fail closed at boot.** The companion is the only thing that can run
315
- * an introspection behavior, so a boot path that refuses on an introspection failure would need
316
- * the companion to fix the companion — see `continuity-drift-and-cas-basis.md` Rule 3.
317
- */
318
- INTROSPECTION = 'introspection',
319
-
320
183
  /**
321
184
  * Rows live in a system reached over an authenticated HTTP API and are queried on demand
322
185
  * (read-through). Decided 2026-08-26 (ETL workstream, D1): this IS a persistence-adapter answer
@@ -830,9 +693,7 @@ export type ResourceConfiguration_BuilderParameters<
830
693
  * stance, erasure stance, and remote-call semantics. The factory enforces presence/absence
831
694
  * coherence and content-validates the declaration.
832
695
  */
833
- httpApiBinding?: HttpApiResourceBinding,
834
- /** REQUIRED when `persistenceAdapter` is INTROSPECTION; meaningless otherwise. */
835
- introspectionBinding?: IntrospectionResourceBinding,
696
+ httpApiBinding?: HttpApiResourceBindingAuthored,
836
697
 
837
698
  /**
838
699
  * OPTIONAL inbound ETL pipeline on an ordinary LOCAL resource — "some resources local, some
@@ -843,7 +704,7 @@ export type ResourceConfiguration_BuilderParameters<
843
704
  * targets exist, accept null unless `required`, and are excludeFromCreate/Update; CLOSED
844
705
  * population refuses caller CREATE operations).
845
706
  */
846
- externalDataPipeline?: ExternalDataPipelineDeclaration,
707
+ externalDataPipeline?: ExternalDataPipelineDeclarationAuthored,
847
708
 
848
709
  isSystemResource?: boolean, // default false - true for core system resources (organizations, users, etc.), false for tenant-specific resources
849
710
 
@@ -1638,8 +1499,6 @@ export type ResourceConfiguration<
1638
1499
  * (factory-enforced both ways). See the authoring-side declaration for the full contract.
1639
1500
  */
1640
1501
  httpApiBinding?: HttpApiResourceBinding,
1641
- /** REQUIRED when `persistenceAdapter` is INTROSPECTION; meaningless otherwise. */
1642
- introspectionBinding?: IntrospectionResourceBinding,
1643
1502
 
1644
1503
  /**
1645
1504
  * The inbound ETL pipeline, when this LOCAL resource declared one — parsed + coherence-checked
@@ -1719,20 +1578,6 @@ export type ResourcesRegistry = {
1719
1578
  resourceConfigurations: {
1720
1579
  [key: ResourceType]: AnyResourceConfiguration ;
1721
1580
  };
1722
- /**
1723
- * The resource types the APPLICATION registered — its own, never the engine's.
1724
- *
1725
- * The registry composes app and core factory maps into one `resourceConfigurations`, which is what
1726
- * every runtime consumer wants. This is the one place the two are still distinguishable, so the
1727
- * split is recorded HERE rather than re-derived by each consumer from a core key set — which would
1728
- * be a second enumeration of a population this file already knows.
1729
- *
1730
- * Its consumer today is the personal-data declaration report, which asks a question only an
1731
- * application author can act on: the engine declares its own posture on ~85 resources, and putting
1732
- * those in front of a reader of a report about THEIR application is how a diagnostic channel stops
1733
- * being read.
1734
- */
1735
- applicationResourceTypes: ResourceType[];
1736
1581
  /**
1737
1582
  * Map of ResourceType to its standard field identifier (e.g., USERS -> userId).
1738
1583
  * Used for FK field resolution without string manipulation.
@@ -155,106 +155,6 @@ export enum ActionPlacement {
155
155
  DANGER_ZONE = 'danger_zone',
156
156
  }
157
157
 
158
- /**
159
- * HOW an operation's action collects its input and shows its result — the chrome the user meets
160
- * when they click the button.
161
- *
162
- * ## Why this axis exists
163
- *
164
- * Until this axis, one rule decided the answer for every custom operation:
165
- * *has a `requestDto` ⇒ navigate*. So an action asking for a single reason string got the same
166
- * full-page treatment as a multi-step wizard, and the only way out was to author
167
- * `navigationOverrides` — per operation, in terms of a zone, a transition verb and an appearance.
168
- * Three concepts to answer one question.
169
- *
170
- * This is that one question. It is a **display-only** axis: backend authorization is untouched and
171
- * `roles` remain the only security authority, exactly like its siblings {@link ActionVisibility},
172
- * {@link ActionPlacement} and {@link ResourceOperationActionScope}.
173
- *
174
- * ## It is an ALIAS, not a parallel mechanism
175
- *
176
- * `MODAL` and `PAGE` do not render anything themselves — they resolve to the navigation transitions
177
- * that already exist (`OVERLAY`, and the ordinary chain), so there is one runtime mechanism and one
178
- * set of zone/appearance/URL semantics. `DIRECT`, `POPOVER` and `INLINE` never enter navigation at
179
- * all, because none of them is a destination: nothing is pushed, no zone changes, and there is
180
- * nothing for a back button to pop. `INLINE` is hosted by the collection the element belongs to —
181
- * see `InPlaceOperationContext` for why that is not the navigation layer's job.
182
- *
183
- * Consequently an explicit `navigationOverrides` entry still WINS over a presentation authored here
184
- * (it is the more specific instrument, and it is checked first in the resolution chain). Author this
185
- * axis to say what KIND of chrome the action wants; author `navigationOverrides` when you need to
186
- * name the zone, the appearance or the viewport yourself.
187
- *
188
- * ## When omitted
189
- *
190
- * It is DERIVED from the operation — see `resolveResourceOperationActionPresentation()`. An
191
- * operation that asks for nothing executes directly; a small field set opens a modal; input the
192
- * framework cannot fit in an overlay (files, nested writes, a large field set) keeps the page it
193
- * has always had. An operation whose `surface` is `ADDRESSABLE` always keeps its page: the author
194
- * has already said it is a deep-linkable destination.
195
- */
196
- export enum ResourceOperationActionPresentation {
197
- /**
198
- * Execute on click, with no form at all — the confirmation dialog for a risky operation is the
199
- * only thing between the click and the request.
200
- *
201
- * Only meaningful for an operation that needs no caller input. Declaring it on an operation that
202
- * DOES have required request fields would send an empty body, so the resolver refuses to derive it
203
- * there and an author who declares it anyway gets the operation's fields dropped — check
204
- * `requestDto` before reaching for this.
205
- */
206
- DIRECT = 'direct',
207
- /**
208
- * A small form anchored to the button that opened it, dismissed by clicking away.
209
- *
210
- * The single-input idiom ("assign to…", "snooze until…"). Transient by construction: no URL, no
211
- * history entry, nothing to deep-link. Use it when the surrounding context is the point — the user
212
- * is reading the row they are acting on and must not lose sight of it.
213
- */
214
- POPOVER = 'popover',
215
- /**
216
- * The element being acted on transforms in place to collect the input, leaving its neighbours
217
- * visible — the row becomes the form rather than being covered by one.
218
- *
219
- * Use it when the surrounding rows are the point: the user is comparing, and an overlay would hide
220
- * the very thing that made them act on this row.
221
- *
222
- * **Transient, like {@link POPOVER}, and for the same reason.** Nothing is pushed, no URL changes,
223
- * and a reload returns the list to rest. An inline row-edit is a momentary state of a listing, not
224
- * a place — which is also why no admin framework deep-links one, and why anything that SHOULD be
225
- * linkable, reloadable or reachable by a back button wants {@link PAGE}.
226
- *
227
- * **It requires a collection.** The host is provided by the list the element belongs to
228
- * (`InPlaceOperationProvider`); the same action rendered on a detail page, in a danger zone or in a
229
- * picker has no row to transform and degrades to an overlay rather than becoming a dead button.
230
- *
231
- * Note it does NOT resolve to `NavigationTransition.INPLACE`. Element-level hosting uses none of
232
- * what the navigation layer offers — no zone, no stack entry, no appearance — and routing it there
233
- * is exactly why that transition has never done what its own docstring promises. See
234
- * `InPlaceOperationContext`.
235
- */
236
- INLINE = 'inline',
237
- /**
238
- * An overlay above the layout — the workhorse for "a handful of fields", and the default the
239
- * derivation reaches for.
240
- *
241
- * Resolves to {@link NavigationTransition.OVERLAY}. The concrete appearance (dialog / sheet /
242
- * drawer / panel) stays the app's decision, resolved from its navigation layout exactly as any
243
- * other overlay: this axis says "an overlay", not "a dialog specifically". Author
244
- * `navigationOverrides` when you need to name one.
245
- */
246
- MODAL = 'modal',
247
- /**
248
- * A routable page, resolved through the ordinary navigation chain (zone transitions, viewport
249
- * overrides, the framework `PUSH` fallback) — i.e. exactly the behaviour every parameterised
250
- * action had before this axis existed.
251
- *
252
- * The right answer for complex or multi-step input, and for anything a user should be able to
253
- * link to, reload, or reach with a back button.
254
- */
255
- PAGE = 'page',
256
- }
257
-
258
158
  /**
259
159
  * Does an operation's action target a SINGLE resource instance, or the WHOLE
260
160
  * collection in the current scope?
@@ -429,15 +329,6 @@ export const ResourceOperationFrontendConfigSchema = z.object({
429
329
  * row id still rides the URL path too, which the handler may ignore.)
430
330
  */
431
331
  rowTargetRequestField: z.string().optional(),
432
- /**
433
- * HOW this action collects its input — see {@link ResourceOperationActionPresentation}.
434
- * Omitted derives from the operation (`resolveResourceOperationActionPresentation`): no input
435
- * executes directly, a small field set opens a modal, complex input keeps its page.
436
- *
437
- * Display-only. An explicit `navigationOverrides` entry is the more specific instrument and wins
438
- * over whatever this resolves to.
439
- */
440
- actionPresentation: z.enum(ResourceOperationActionPresentation).optional(),
441
332
  customView: z.any().optional(),
442
333
  displayPresetOverride: z.object({
443
334
  resourceLayoutPresetKey: z.string().optional(),
@@ -296,6 +296,8 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
296
296
  gives up and the industry precedent.
297
297
  - `references/pipeline-destination-schema.md` — the destination schema rules, and what each refusal
298
298
  message is telling you.
299
+ - `references/framework-pipeline-admin-endpoints-api.md` — run a pipeline on demand while authoring
300
+ its mapping, and read what each one last did (`cursor`, `loadStatus`).
299
301
 
300
302
  ## Verification
301
303
 
@@ -35,9 +35,35 @@ the one sanctioned exception is the declared external-erasure call that a subjec
35
35
  ```typescript
36
36
  export enum HttpApiTransportDialect {
37
37
  /**
38
- * OData v4 (SAP S/4HANA, Microsoft Dataverse/Dynamics 365): one generic client — mechanical
39
- * pushdown of `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata`
40
- * boot-time verification probe of the committed declaration.
38
+ * OData **v4** — one generic client: mechanical pushdown of
39
+ * `$filter`/`$select`/`$top`/`$skip`/`$orderby`/`$count`, with a `$metadata` boot-time
40
+ * verification probe of the committed declaration.
41
+ *
42
+ * ⚠ **This member is v4 ONLY, and that excludes SAP's most-used API.** An earlier revision of
43
+ * this comment named "SAP S/4HANA, Microsoft Dataverse/Dynamics 365" here, which is half right
44
+ * and was load-bearing — it is why nobody looked:
45
+ *
46
+ * | Target | Version | Consumable today |
47
+ * |---|---|---|
48
+ * | Microsoft Dataverse / Dynamics 365 Web API (`/api/data/v9.2/`) | v4 | ✅ |
49
+ * | SAP S/4HANA OData **v4** services (`/sap/opu/odata4/…`) | v4 | ✅ |
50
+ * | SAP `API_BUSINESS_PARTNER` (`/sap/opu/odata/sap/API_BUSINESS_PARTNER`) | **v2** | ❌ |
51
+ *
52
+ * v2 is not a v4 variant with a different header. Its collection envelope is
53
+ * `{ "d": { "results": [...], "__next": …, "__count": … } }` rather than
54
+ * `{ "value": [...], "@odata.nextLink": … }`; `Edm.DateTime` serializes as `"/Date(<ticks>)/"`
55
+ * rather than ISO 8601; `Edm.Decimal` and `Edm.Int64` serialize as JSON STRINGS rather than
56
+ * numbers; and JSON must be requested (`$format=json`) because v2 defaults to Atom/XML. So it
57
+ * changes the envelope, the paging property, the count property AND the value encoding — a
58
+ * reader written for one cannot read the other, and the mapping layer needs coercions the way
59
+ * Odoo needs `ODOO_FALSE_AS_NULL`.
60
+ * spec-cite: OData Version 2.0 JSON Format
61
+ * (https://www.odata.org/documentation/odata-version-2-0/json-format/) — the `d`/`results`/
62
+ * `__next`/`__count` envelope, the `/Date(<ticks>)/` DateTime literal, and Edm.Decimal /
63
+ * Edm.Int64 "formatted as a JSON string".
64
+ *
65
+ * Supporting v2 is an OPEN decision, not an oversight. Until it lands, point an ODATA binding at
66
+ * a v4 service: for SAP that means the OData v4 edition of the API where one is published.
41
67
  */
42
68
  ODATA = 'odata',
43
69
 
@@ -0,0 +1,70 @@
1
+ # Pipeline admin endpoints — run one now, and see what each last did
2
+
3
+ Read this when:
4
+
5
+ - you are authoring a pipeline's field mapping and do not want to wait for `scheduleCron`;
6
+ - a pipeline appears not to have run, and you need to know whether it is DECLARED but has never run
7
+ (no state at all) versus mid-pass (a non-null cursor);
8
+ - a sync reported success but a row did not change, and you need the load's own verdict.
9
+
10
+ The listing is declaration-first: a pipeline that has never run still appears, with a null state.
11
+ That is deliberate — a pipeline missing from a state-first listing is exactly the one you are
12
+ looking for.
13
+
14
+ Two fields decide most questions:
15
+
16
+ - **`cursor`** — non-null means a pass is IN FLIGHT. The next run continues it rather than starting
17
+ a fresh pass, and the orphan stage does not run, because "absent from a partial extraction" is not
18
+ evidence of remote deletion.
19
+ - **`loadStatus`** — the seed engine's verdict on the WRITE, which is a different axis from whether
20
+ the extraction pass completed. A full pass can still fail to write some of what it read; when this
21
+ is not `completed`, read the run ledger row named by `seedRunId` for the per-entry detail.
22
+
23
+ The endpoints are mounted only when the admin secret is configured, and answer `503` otherwise.
24
+
25
+ ## Import Origins
26
+
27
+ - `@wildo-ai/saas-backend-lib`
28
+
29
+ ## Source Excerpts
30
+
31
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
32
+
33
+ ```typescript
34
+ /**
35
+ * Environment variable holding the secret these endpoints require. When unset or empty EVERY
36
+ * endpoint answers 503 — the safe default, so a fresh deployment never accidentally exposes an
37
+ * operator surface that can reach a third party's production system.
38
+ *
39
+ * Deliberately the SAME key data-seeding uses: an operator administering one app has one admin
40
+ * secret, and minting a second would mean two rotations to remember and one of them forgotten.
41
+ */
42
+ export const ExternalDataAdminEndpointEnvKey = 'APPLICATION_ADMIN_SECRET' as const;
43
+
44
+ /** Header carrying the secret. Hash-then-`timingSafeEqual`, per the sibling controller. */
45
+ export const ExternalDataAdminEndpointHeaderKey = 'X-Admin-Secret' as const;
46
+
47
+ /**
48
+ * Root mount. Under `/internal/...` rather than `/api/v1/...` because this is an operator surface,
49
+ * not a consumer API — the convention `/health` and the data-seeding admin surface already follow.
50
+ */
51
+ export const ExternalDataAdminEndpointMountBasePath = '/internal/admin/external-data' as const;
52
+
53
+ /** Sub-paths, relative to {@link ExternalDataAdminEndpointMountBasePath}. */
54
+ export const ExternalDataAdminEndpointPath = {
55
+ /** GET — every declared pipeline with its persisted cursor and last-run summary. */
56
+ PIPELINES: '/pipelines',
57
+ /**
58
+ * POST — run ONE pipeline now. `{ "resourceType": "externalCustomers" }`.
59
+ *
60
+ * This exists because a scheduled-only capability is undevelopable: authoring a mapping against
61
+ * SAP or Dynamics means change → sync → look, dozens of times, and an hourly cron makes that loop
62
+ * unusable. Verifying the first dogfood required either waiting an hour or editing committed app
63
+ * config, which is what proved the door was missing.
64
+ */
65
+ RUN: '/run',
66
+ } as const;
67
+
68
+ export type ExternalDataAdminEndpointPathValue =
69
+ (typeof ExternalDataAdminEndpointPath)[keyof typeof ExternalDataAdminEndpointPath];
70
+ ```
@@ -246,7 +246,6 @@ shared schema declares the **truth**, the UI behavior file declares the
246
246
  - `references/framework-schema-family-api.md` — source-backed `createSchemaFamily` contract
247
247
  - `references/framework-polymorphic-resources-api.md` — source-backed `PolymorphicVariantDefinition` + `optOutPolymorphicAutoBusinessKey` contract
248
248
  - `references/framework-decorator-vocabulary-api.md` — source-backed `ZodDecorator` enum + `SCHEMA_METADATA` symbol
249
- - `references/framework-personal-data-category-api.md` — source-backed `.dataCategories()` + `PersonalDataCategory` vocabulary, for any field holding personal data
250
249
  - `references/framework-zod-lifecycle-and-chainable-api.md` — lifecycle structural params + chainable runtime (`initZodDecorators` alignment)
251
250
  - `examples/add-enum-field-with-ui.example.md` — worked three-layer example
252
251
  - `examples/basic-resource-schema.example.md` — full from-scratch resource schema
@@ -32,23 +32,6 @@ When the answer is "shared schema", choose the next reference by need:
32
32
  - `field-type-selection.md` -> whether the field should be primitive, enum, FK, or a domain factory
33
33
  - `special-factories.md` -> when to use `z_money()`, `z_file()`, `z_range()`, and similar helpers
34
34
  - `schema-variants-and-discriminators.md` -> discriminator and schema-family changes
35
- - `framework-personal-data-category-api.md` -> the field holds data about a PERSON and needs a
36
- `.dataCategories(...)` declaration
37
-
38
- ## Personal data is a shared-schema concern
39
-
40
- If the field holds data about a person, the shared schema is where you say so — all four axes live
41
- there and none of them is a UI or specification concern:
42
-
43
- | Question | Declaration |
44
- |---|---|
45
- | What KIND of personal data? | `.dataCategories(PersonalDataCategory.…)` |
46
- | What happens on ERASURE? | `.impersonalizeWith(RedactionType.…)` |
47
- | Where did it come from (Art. 20)? | `.portabilityProvenance(DataPortabilityProvenance.…)` |
48
-
49
- Declare the category on the same line you declare the scrub treatment. A field carrying one and not
50
- the other is reported by name as an OUTSTANDING gap in every compliance document the application
51
- produces — the application has said the field holds personal data and has not said what kind.
52
35
 
53
36
  ## Escalate Early
54
37
 
@@ -60,40 +60,6 @@ export enum ZodDecorator {
60
60
  * `SUBJECT_PROVIDED` and masked on erasure.
61
61
  */
62
62
  PORTABILITY_PROVENANCE = "portabilityProvenance",
63
- /**
64
- * Data categories: WHICH KINDS of personal data this field holds — one or more
65
- * `PersonalDataCategory` values (strings), read by the compliance fact producer to answer the
66
- * privacy-notice question "which categories of personal data do you process".
67
- *
68
- * Authored fluently: `email: z.email().dataCategories(PersonalDataCategory.CONTACT_DETAILS)`, or
69
- * with an array when a field genuinely spans two —
70
- * `.dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])`.
71
- * The chokepoint normalizes either form to a deduped array, so every reader sees one shape.
72
- * At least one category is REQUIRED and each must be a non-empty string: a blank declaration
73
- * would read back as declared-but-meaningless, which is worse than absent, because absence is
74
- * what the gap report is looking for. `addDataCategories(schema, categories)` is the equivalent
75
- * programmatic escape hatch; read them back with `getDataCategories(schema)`.
76
- *
77
- * WHETHER each value is a real `PersonalDataCategory` member is checked by the resource factory's
78
- * boot guard, which owns the enum — this layer knows only that non-empty strings were declared.
79
- *
80
- * ⚠️ Four adjacent axes, none of them this one. {@link ZodDecorator.IMPERSONALIZE_WITH} says what
81
- * happens to the value on ERASURE; {@link ZodDecorator.PORTABILITY_PROVENANCE} says where it CAME
82
- * FROM; `Compliance_DataClassification` is a SENSITIVITY ladder for flows-actors config; a
83
- * retention class says HOW LONG it is kept. A single field is routinely all five at once, and
84
- * none of the other four can answer "what kind of personal data is this".
85
- *
86
- * ⚠️ Do NOT declare a category on a field merely because its NAME suggests one. The decorator
87
- * exists precisely so categories are never derived from identifiers: `email`, `phone` and
88
- * `dateOfBirth` are suggestive while `notes` is not, and an inventory assembled by
89
- * pattern-matching names is a guess whose misses are silently undisclosed. `CREDENTIALS` is the
90
- * one category the producer derives, and it derives it from `.isPassword()` / `.isOtp()` /
91
- * `.isWriteOnlySecret()` — markers the author wrote, not names it read.
92
- *
93
- * assurance-control: WILDO.PRIVACY.PERSONAL_DATA_INVENTORY — the application declares which
94
- * categories of personal data each field holds
95
- */
96
- DATA_CATEGORIES = "dataCategories",
97
63
  /**
98
64
  * Audit evidence: this field's BEFORE/AFTER VALUES are recorded when a resource operation
99
65
  * mutates it, on the `resource_operation_performed` audit event.
@@ -266,12 +232,6 @@ export type ZodDecorator_ParamsType = {
266
232
  * normalize; if a second axis is ever needed the chokepoint widens exactly as that one did.
267
233
  */
268
234
  [ZodDecorator.PORTABILITY_PROVENANCE]: string;
269
- /**
270
- * The field's personal-data categories — `PersonalDataCategory` values, typed as plain strings at
271
- * this layer (zod-decorators sits below saas-models and cannot import the enum). Accepts a single
272
- * value (the common case) or an array; the chokepoint normalizes either to a deduped array.
273
- */
274
- [ZodDecorator.DATA_CATEGORIES]: string | readonly string[];
275
235
  // Audit-evidence marker — parameterless, like IS_BUSINESS_KEY. A field either is evidence or is
276
236
  // not; there is no axis to parameterize, and adding one would invite per-field redaction policy
277
237
  // to grow here instead of on the impersonalization decorator that owns it.
@@ -364,11 +324,6 @@ export type ZodDecorator_Types = {
364
324
  * (zod-decorators sits below saas-models). Stored exactly as authored; the chokepoint only
365
325
  * rejects blanks. */
366
326
  [ZodDecorator.PORTABILITY_PROVENANCE]: string;
367
- /** Personal-data categories — `PersonalDataCategory` values carried as opaque `string`s
368
- * (zod-decorators sits below saas-models). ALWAYS the normalized array, deduped and non-empty:
369
- * the chokepoint widens a bare single-value authoring form on the way in, so every reader sees
370
- * one shape and `getDataCategories` can answer "is this field categorized?" by presence alone. */
371
- [ZodDecorator.DATA_CATEGORIES]: readonly string[];
372
327
  /** Audit-evidence marker — stored as the bare `true` sentinel (parameterless, like IS_BUSINESS_KEY). */
373
328
  [ZodDecorator.IS_AUDIT_EVIDENCE]: true;
374
329
  /** RAG-source config — ALWAYS the normalized object ( `{}` when authored with no argument): the
@@ -474,7 +429,6 @@ export interface CustomFieldMetadata {
474
429
  [ZodDecorator.IS_WRITE_ONLY_SECRET]?: ZodDecorator_Types[ZodDecorator.IS_WRITE_ONLY_SECRET];
475
430
  [ZodDecorator.IMPERSONALIZE_WITH]?: ZodDecorator_Types[ZodDecorator.IMPERSONALIZE_WITH];
476
431
  [ZodDecorator.PORTABILITY_PROVENANCE]?: ZodDecorator_Types[ZodDecorator.PORTABILITY_PROVENANCE];
477
- [ZodDecorator.DATA_CATEGORIES]?: ZodDecorator_Types[ZodDecorator.DATA_CATEGORIES];
478
432
  [ZodDecorator.IS_AUDIT_EVIDENCE]?: ZodDecorator_Types[ZodDecorator.IS_AUDIT_EVIDENCE];
479
433
  [ZodDecorator.RAG_SOURCE]?: ZodDecorator_Types[ZodDecorator.RAG_SOURCE];
480
434
  [ZodDecorator.IS_VIRTUAL]?: ZodDecorator_Types[ZodDecorator.IS_VIRTUAL];
@@ -761,32 +761,6 @@ function applySingleDecorator<T extends z.ZodTypeAny>(
761
761
  currentMetadata[ZodDecorator.PORTABILITY_PROVENANCE] = raw;
762
762
  break;
763
763
  }
764
- case ZodDecorator.DATA_CATEGORIES: {
765
- // NORMALIZE HERE, not in the doors — the impersonalizeWith discipline. A single value (the
766
- // common case) and an array both store a deduped ARRAY, so every reader sees one shape and
767
- // `getDataCategories` answers "is this field categorized?" by presence alone.
768
- //
769
- // Fail LOUD on an empty declaration. An UNCATEGORIZED field is a legitimate, common state —
770
- // most fields are not personal data — and the gap report is built on ABSENCE. A stored empty
771
- // array would read back as declared-with-no-categories, which is invisible to a report
772
- // looking for absence: the field would be silently excluded from the notice while looking
773
- // annotated to anyone reading the schema.
774
- //
775
- // WHETHER each value is a real `PersonalDataCategory` member is checked by the resource
776
- // factory's boot guard, which owns the enum — this layer knows only that non-empty strings
777
- // were declared.
778
- const raw = p as unknown;
779
- const authored: readonly unknown[] = Array.isArray(raw) ? raw : [raw];
780
- if (authored.length === 0 || authored.some((value) => typeof value !== 'string' || value.trim().length === 0)) {
781
- throw new Error(
782
- `dataCategories(categories) requires at least one non-empty PersonalDataCategory value (received ${JSON.stringify(raw)}). ` +
783
- `A field that holds no personal data carries NO declaration — absence is what a category gap report reads. ` +
784
- `An empty declaration looks annotated and discloses nothing.`,
785
- );
786
- }
787
- currentMetadata[ZodDecorator.DATA_CATEGORIES] = [...new Set(authored as readonly string[])];
788
- break;
789
- }
790
764
  case ZodDecorator.IS_AUDIT_EVIDENCE:
791
765
  currentMetadata[ZodDecorator.IS_AUDIT_EVIDENCE] = true;
792
766
  break;
@@ -16,7 +16,7 @@ Source-backed display and edit mode contracts for form chrome.
16
16
  *
17
17
  * These values are not the persisted resource semantics themselves. They are
18
18
  * consumed by the frontend resource UI behavior layer, typically in
19
- * files like `frontend/src/modules/<module>/resources/<resource>/<resource>.ui-behavior.tsx`, where the AI
19
+ * files like `app/src/modules/<module>/resources/<resource>/<resource>.ui-behavior.tsx`, where the AI
20
20
  * calls decorators like `.stringUI()`, `.enumUI()`, `.booleanUI()`, etc. on the
21
21
  * schema shape exposed to `resourceUIBehavior(...)`.
22
22
  *