@wildo-ai/framework-knowledge 1.1.13 → 1.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
  4. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
  5. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  6. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.definitions.js +9 -0
  8. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  11. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  13. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  15. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  16. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  17. package/dist/knowledge/manifest.json +7 -7
  18. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  19. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  20. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  21. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  22. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  23. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  25. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  27. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  28. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
  29. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  30. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  31. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  32. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  33. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  34. package/dist/knowledge/references/example.config.navigation.full.md +14 -0
  35. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
  36. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
  37. package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
  38. package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
  39. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  40. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  41. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  42. package/dist/knowledge/references/integration-plan.config.md +78 -8
  43. package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
  44. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  45. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  47. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  48. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
  49. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  50. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  51. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  52. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  53. package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
  54. package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
  55. package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
  56. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  59. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  60. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  61. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  62. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  63. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  64. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  65. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  66. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  67. package/dist/knowledge/registries/framework-topics.json +45 -1
  68. package/dist/knowledge/registries/playbooks.json +2 -2
  69. package/dist/knowledge/registries/source-tags.json +1175 -1107
  70. package/dist/knowledge/skills/INDEX.md +2 -2
  71. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
  72. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  73. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  74. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  75. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
  76. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
  77. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  78. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  79. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  80. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  81. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  82. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  83. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
  84. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
  85. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  86. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
  87. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  88. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  89. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  90. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  91. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  92. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  93. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  94. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
  95. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  96. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
  97. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
  98. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  99. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
  100. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  101. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  102. package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
  103. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
  104. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  105. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  106. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  107. package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
  108. package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
  109. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  110. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  111. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  112. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  113. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  114. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  115. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  116. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  117. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
  118. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  119. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  120. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  121. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  122. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  123. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  124. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  125. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  126. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  127. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  128. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  129. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  130. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  131. package/dist/knowledge/topic-index.json +326 -179
  132. package/dist/tsconfig.build.tsbuildinfo +1 -1
  133. package/package.json +4 -4
@@ -120,9 +120,10 @@ export. The typed shape carries:
120
120
  now `source: MANAGED, provider: 'atlas'`
121
121
  - `serviceProfile` (optional) — `EnvironmentServiceProfile.FULL` (the
122
122
  default) or `SMALL`: which optional services the environment runs.
123
- `SMALL` runs no ClamAV, no immudb and no mongot, and one database
124
- family. See "A smaller footprint: `serviceProfile`" below for what
125
- each one costs you
123
+ `SMALL` runs no ClamAV, no immudb and no mongot, one database
124
+ family, and its background work on the application's own database
125
+ (minions only on PostgreSQL). See "A smaller footprint: `serviceProfile`" below
126
+ for what each one costs you
126
127
  - `logging` — `{ level, formattedConsoleErrors }` projected to the
127
128
  process env as `LOG_LEVEL` / `LOG_FORMATTED_CONSOLE_ERRORS` by
128
129
  `env-vars-builder` and consumed at boot by
@@ -806,14 +807,19 @@ receives. No application receives it.
806
807
  A small internal tool for one team does not need every service the full
807
808
  platform runs. `serviceProfile: EnvironmentServiceProfile.SMALL` (import
808
809
  it from `@wildo-ai/platform-config-lib`) keeps the services the platform
809
- cannot run without (one database, the cache, the broker and the object
810
- store) and drops three optional ones:
810
+ cannot run without (one database, the cache and the object store) and
811
+ drops three optional ones. Its background work (queued jobs, scheduled
812
+ batches) runs on the application's own database instead of RabbitMQ, and the
813
+ environment runs no broker at all: no RabbitMQ container, no `RABBITMQ_*`
814
+ settings, no broker credential. A `backingServices.rabbitmq` declaration beside
815
+ `SMALL` is refused; remove it when you switch an environment to `SMALL`:
811
816
 
812
817
  | Service the profile drops | Capability it backs | What happens if the application declares the capability anyway |
813
818
  |---|---|---|
814
819
  | ClamAV | Antivirus scanning of uploads (`z_file({ scanPolicy: 'required' })`) | The backend refuses to start, naming the profile and the fields. A field that only PREFERS a scan still uploads, unscanned, exactly as with no scanner |
815
820
  | immudb | The tamper-evident store of `COMPLIANCE_AUDIT_TRAIL` | The backend refuses to start when the capability is enabled and no audit provider resolves. The database audit trail (Layer 1) always runs |
816
821
  | mongot | Vector and text search for `.ragSource()` fields on a **MongoDB**-persisted resource | The backend refuses to start, naming the profile and the resources. On **PostgreSQL** nothing changes: pgvector runs inside the database |
822
+ | RabbitMQ (as the application's queue) | Minions (`minions` in `wildo.saas.config.ts`) | On **PostgreSQL** nothing changes for you: each minion's database role reaches only its own queues there (a row-level security policy the platform applies when it provisions the minion), as its RabbitMQ credential would. On **MongoDB**, which cannot confine a minion that way, minions are refused when the environment is rendered (`wildo config sync`, compose and Kubernetes) and when a minion boots, naming the profile. Remove the minions, move the application to PostgreSQL (`applicationDatabase.engine`), or use `FULL` |
817
823
 
818
824
  The refusals are the point. A capability that looks enabled and does
819
825
  nothing is worse than one that is refused: an upload certified "clean"
@@ -846,6 +852,10 @@ Rules the descriptor enforces when the file is parsed:
846
852
  - `SMALL` beside `backingServices.clamav` or `.immudb` with
847
853
  `source: SELF` is refused. The two statements contradict each other;
848
854
  remove one.
855
+ - `SMALL` beside any `backingServices.rabbitmq` declaration is refused:
856
+ the profile runs no broker, so a self-hosted one contradicts it and a
857
+ managed one would be a broker nothing uses. A hosted application that
858
+ declares a vhost on a `SMALL` host is refused the same way.
849
859
  - `SMALL` with two database families is refused, and the message names
850
860
  the declarations that bring each one in: a second store in
851
861
  `backingServices`, a platform `database.engine` that differs from the
@@ -864,17 +874,33 @@ record that contradicts the profile, for an environment whose
864
874
  `config.json` was written before the profile was authored: run
865
875
  `wildo config sync` after changing the descriptor.
866
876
 
867
- What `SMALL` does not drop yet: **RabbitMQ**. The platform's scheduler
868
- delivers scheduled work to the application's queue from another process,
869
- and no queue that survives a restart runs on the cache or the database
870
- today, so the broker stays under every profile.
877
+ Under `SMALL` the platform's scheduler delivers each scheduled run to the
878
+ application backend over HTTP, and the backend queues it in its own
879
+ database, so nothing needs a broker: RabbitMQ is not rendered on either
880
+ lane and the platform mints no broker credential for any application.
881
+
882
+ On a local Kubernetes (Kind) environment the scheduler runs in the
883
+ cluster while the backends run on your machine, so its pod reaches them
884
+ at `host.docker.internal`, as compose does. Docker Desktop resolves that
885
+ name inside the cluster; on Docker Engine for Linux the pod maps it to
886
+ the Docker bridge gateway, which the backend also listens on. Rootless
887
+ Docker has no such address, and scheduled runs there stay undelivered:
888
+ each retry records the host gateway address the scheduler dialled.
871
889
 
872
890
  Moving between profiles migrates no data. Going to `SMALL`, the next
873
891
  `wildo local dev` / `wildo local up` stops the dropped containers and
874
- keeps their data volumes. Going back to `FULL`, each service starts
892
+ keeps their data volumes. Jobs still queued in RabbitMQ at that moment
893
+ are not moved to the database queue: let the queues drain (or accept
894
+ losing what is left) before switching. Going back to `FULL`, each service starts
875
895
  from what it kept or from empty: mongot rebuilds its indexes from the
876
- collections, and a new immudb holds no earlier audit history (the
877
- database audit trail does).
896
+ collections, a new immudb holds no earlier audit history (the
897
+ database audit trail does), and RabbitMQ starts from the data it kept:
898
+ the broker users and vhosts it held come back, and an application with
899
+ none is minted its credentials at its next registration (the next
900
+ `wildo local dev`). An application withdrawn while the environment was
901
+ `SMALL` could not have its broker credentials revoked (the withdrawal
902
+ names them); withdraw it again after switching back, or delete the
903
+ broker's data directory before switching.
878
904
 
879
905
  ## Choosing the application's store — and what it obliges
880
906
 
@@ -1042,7 +1068,7 @@ Read `references/framework-infrastructure-host-api.md` for the source-backed con
1042
1068
  - [ ] Every backing service the app uses is declared with a valid `source`
1043
1069
  - [ ] Every declaration is one the platform can serve (see "What each kind can be declared as today") — `wildo config validate --domain config` reports no `names no infrastructure provider` / `which no provider module can serve yet` finding
1044
1070
  - [ ] Every capability-required backing service is declared in **every** environment (see "Capability-driven backing services") — `wildo config sync` emits no missing-backing-store warning
1045
- - [ ] A `SMALL` `serviceProfile` declares no `clamav` / `immudb` with `source: SELF`, runs one database family (one of `mongodb` / `postgresql` in `backingServices`, and `database.engine` equal to `applicationDatabase.engine`), and the application declares none of the capabilities the profile drops (or accepts the boot refusal as the reminder) — see "A smaller footprint"
1071
+ - [ ] A `SMALL` `serviceProfile` declares no `clamav` / `immudb` with `source: SELF`, runs one database family (one of `mongodb` / `postgresql` in `backingServices`, and `database.engine` equal to `applicationDatabase.engine`), and the application declares none of the capabilities the profile drops, and no minions unless it persists to PostgreSQL (or accepts the refusal as the reminder) — see "A smaller footprint"
1046
1072
  - [ ] No secret values in the file (passwords, keys, tokens — all referenced via the secrets store)
1047
1073
  - [ ] Every vendor identifier issued per deployment (OAuth client ID, frontend SDK DSN or site key) is authored in THIS file's `providerConfigurations`, and none is authored in `wildo.saas.config.ts`
1048
1074
  - [ ] Local `devCompanion` is optional; remote environments declare `runtimeEnvironment`; remote Kubernetes also requires `remoteProvider`; optional `deployment` matches the chosen workflow
@@ -154,18 +154,27 @@ export function resolveDefaultLocalDataStorage(locationType: WildoLocationType):
154
154
  * Both lanes render a profile: the Docker Compose generator, and the Kubernetes manifests (workloads, the mongod
155
155
  * routing parameters, secrets, persistent volumes and readiness) since #2303's second slice.
156
156
  *
157
- * ## What it does not change yet
157
+ * ## The queue
158
158
  *
159
- * The broker. RabbitMQ stays a platform dependency under every profile: the platform scheduler publishes onto the
160
- * application's queue from another process, and no durable queue runs on the cache or the database
161
- * (`QueueAdapterType.MEMORY` is in-process only). Tracked by #2303.
159
+ * `SMALL`'s background work runs on the application's own database (`QueueAdapterType.DATABASE`, selected by
160
+ * `queueAdapterTypeOfEnvironmentServiceProfile`), and the platform scheduler delivers its occurrences to the backend over
161
+ * HTTP rather than onto a broker. A minion is confined to its own queues there by a PostgreSQL row-level security policy;
162
+ * MongoDB has none, so a MongoDB application's minions are refused under `SMALL` (`describeMinionsRefusedByEnvironmentServiceProfile`).
163
+ *
164
+ * ## No broker
165
+ *
166
+ * Since #2303 slice D a `SMALL` environment runs no RabbitMQ at all (`environmentServiceProfileRunsMessageBroker`): neither
167
+ * lane renders it, no env file carries `RABBITMQ_*`, no runtime joins its network segment, and apps-manager (told through
168
+ * `PLATFORM_ENVIRONMENT_SERVICE_PROFILE`) initializes no admin client and mints, revokes or restores no vhost or credential.
169
+ * A `backingServices.rabbitmq` declaration beside it is refused.
162
170
  */
163
171
  export enum EnvironmentServiceProfile {
164
172
  /** Every service the environment's declarations ask for. The default when nothing is authored. */
165
173
  FULL = 'full',
166
174
  /**
167
175
  * The footprint for a small deployment: no ClamAV, no immudb, no mongot
168
- * ({@link servicesOmittedByEnvironmentServiceProfile}). Vector search remains available on PostgreSQL
176
+ * ({@link servicesOmittedByEnvironmentServiceProfile}), one database family, and background work on the application's
177
+ * own database instead of RabbitMQ, which it does not run (minions only on PostgreSQL). Vector search remains available on PostgreSQL
169
178
  * (pgvector is part of the PostgreSQL image, not a separate service).
170
179
  */
171
180
  SMALL = 'small',
@@ -221,6 +230,76 @@ export function environmentServiceProfileRunsOneDatabaseFamily(profile: Environm
221
230
  }
222
231
  }
223
232
 
233
+ /**
234
+ * The queue an environment's application processes share (#2303), as its profile decides it. Total over
235
+ * {@link EnvironmentServiceProfile}: a member added tomorrow fails the build until somebody decides.
236
+ *
237
+ * `FULL` runs RabbitMQ; `SMALL` exists to run without a broker, so its processes share the DATABASE queue, kept in
238
+ * the application's own database (`QueueAdapterType.DATABASE`). Read by the application's container when it binds its
239
+ * queue adapter, so the backend and its minions (which receive the same profile) always choose the same queue.
240
+ *
241
+ * Derived rather than authored: a separate `queueTransport` field beside `serviceProfile` was considered and rejected.
242
+ * `FULL` with the database queue would run a broker nothing uses, and `SMALL` with RabbitMQ would defeat the profile's
243
+ * purpose; neither has a use, and a second field would let them be declared.
244
+ */
245
+ export function queueAdapterTypeOfEnvironmentServiceProfile(profile: EnvironmentServiceProfile): QueueAdapterType {
246
+ switch (profile) {
247
+ case EnvironmentServiceProfile.FULL:
248
+ return QueueAdapterType.RABBITMQ;
249
+ case EnvironmentServiceProfile.SMALL:
250
+ return QueueAdapterType.DATABASE;
251
+ }
252
+ }
253
+
254
+ /**
255
+ * Whether an environment under `profile` runs a message broker at all (#2303 slice D). Derived from
256
+ * {@link queueAdapterTypeOfEnvironmentServiceProfile}, never authored: the broker exists to carry the RabbitMQ queue, and
257
+ * under the DATABASE queue nothing in the environment uses one (the platform scheduler delivers over HTTP). Absent profile
258
+ * ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}.
259
+ *
260
+ * The ONE answer every broker decision reads: whether a deployment lane renders RabbitMQ, whether an env file carries
261
+ * `RABBITMQ_*`, whether apps-manager initializes its RabbitMQ admin client and mints a vhost and credentials, and whether
262
+ * a `backingServices.rabbitmq` declaration contradicts the profile. Total over the queue vocabulary through the switch
263
+ * below, so a third queue adapter must decide here whether it needs a broker.
264
+ */
265
+ export function environmentServiceProfileRunsMessageBroker(profile: EnvironmentServiceProfile | undefined): boolean {
266
+ switch (queueAdapterTypeOfEnvironmentServiceProfile(profile ?? DEFAULT_ENVIRONMENT_SERVICE_PROFILE)) {
267
+ case QueueAdapterType.RABBITMQ:
268
+ return true;
269
+ case QueueAdapterType.DATABASE:
270
+ case QueueAdapterType.MEMORY:
271
+ return false;
272
+ }
273
+ }
274
+
275
+ /**
276
+ * Why an application that declares minions cannot run under `profile` on `applicationDatabaseEngine`, or undefined when it
277
+ * can (#2303).
278
+ *
279
+ * Under the DATABASE queue a minion takes its ticks from the application's shared queue table, where a plain table grant
280
+ * would let it read and delete every queued job of its application; its RabbitMQ credential is confined to its own
281
+ * queues. On PostgreSQL the same confinement is a row-level security policy (`deriveMinionDatabaseQueueConfinement`,
282
+ * applied through the owed-grants contract), so minions run. MongoDB has no row-level security, so a MongoDB
283
+ * application's minions are refused under that queue, at render and at boot, with the remedy named. Both refusals read
284
+ * this one function.
285
+ */
286
+ export function describeMinionsRefusedByEnvironmentServiceProfile(
287
+ profile: EnvironmentServiceProfile,
288
+ applicationDatabaseEngine: DatabaseEngine,
289
+ ): string | undefined {
290
+ if (queueAdapterTypeOfEnvironmentServiceProfile(profile) !== QueueAdapterType.DATABASE) return undefined;
291
+ switch (applicationDatabaseEngine) {
292
+ case DatabaseEngine.POSTGRESQL:
293
+ return undefined;
294
+ case DatabaseEngine.MONGODB:
295
+ return `This environment runs the '${profile}' service profile (\`serviceProfile\` in wildo.infra.<env>.config.ts), whose `
296
+ + 'background work runs on the application\'s own database instead of RabbitMQ, and the application persists to '
297
+ + 'MongoDB, which cannot confine a minion to its own queues there (only PostgreSQL row-level security can). Remove the '
298
+ + `minions from wildo.saas.config.ts, set applicationDatabase.engine to '${DatabaseEngine.POSTGRESQL}', or set `
299
+ + `serviceProfile to '${EnvironmentServiceProfile.FULL}'.`;
300
+ }
301
+ }
302
+
224
303
  /** Whether `profile` omits `service`. Absent profile ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}. */
225
304
  export function environmentServiceProfileOmits(
226
305
  profile: EnvironmentServiceProfile | undefined,
@@ -224,6 +224,36 @@ export const SHELL_GHOST_LAYER_ATTRIBUTE = 'data-shell-ghost-layer';
224
224
  /** The attribute every ghost carries, with its kind (`ShellGhostKind`). */
225
225
  export const SHELL_GHOST_ATTRIBUTE = 'data-shell-ghost';
226
226
 
227
+ /**
228
+ * The markers a still picture of an engine element must NOT carry: everything a query for the real element, or for a
229
+ * control inside it, finds it by. A picture (a discarded pane leaving, an image behind an expanded pane, a pressed row
230
+ * flying into its pane) is inert and takes no pointer, but it is still in the document while it fades, and a picture
231
+ * that kept these was found by those queries as though it were the thing it shows.
232
+ *
233
+ * Measured 2026-11-14 on Your Application (morph layout): a closed todo pane's picture kept `data-navigation-back` for the
234
+ * ~650ms it took to leave, so a lookup of the pane's back control found the picture's (#3764 had to wait it out in
235
+ * `browser-nav-zones`). It never took a click (inert, `pointer-events: none`: the point under it hit the list), but
236
+ * the zone's own back control is identified by that attribute, and a picture must not answer to it.
237
+ *
238
+ * Styling hooks (`data-slot`, `data-state`) are NOT here: a picture keeps the look of what it shows. A caller that
239
+ * needs a narrower picture strips more on its own.
240
+ */
241
+ export const SHELL_PICTURE_STRIPPED_ATTRIBUTES: readonly string[] = [
242
+ 'id',
243
+ // The engine's pane and region markers.
244
+ 'data-content-area',
245
+ 'data-panel-id',
246
+ 'data-zone-hidden',
247
+ 'data-zone-emphasized',
248
+ 'data-component-area',
249
+ SHELL_OBJECT_ATTRIBUTE,
250
+ // The engine's control hooks: a zone's back control, an operation's trigger, a navigation item, a rail entry.
251
+ 'data-navigation-back',
252
+ 'data-operation-id',
253
+ 'data-nav-item-id',
254
+ 'data-ref',
255
+ ];
256
+
227
257
  /** The two kinds of ghost. */
228
258
  export enum ShellGhostKind {
229
259
  /** A dismissed side pane, flying away. */
@@ -272,6 +272,32 @@ wildo local deregister --reason "scratch application, no longer used"
272
272
  wildo local restore && wildo local dev
273
273
  ```
274
274
 
275
+ ### `wildo local jobs` / `wildo local jobs run`
276
+
277
+ Run one of the application's scheduled jobs NOW instead of waiting for its next tick, on the platform
278
+ the active environment names. Run from the application root; `--app <slug>` disambiguates.
279
+
280
+ | Command | Effect |
281
+ |------|--------|
282
+ | `wildo local jobs` | Lists the application's scheduled jobs, each with the selector `run` takes, beside the number of jobs the scheduler holds for every application (an empty list beside a total of 0 means the scheduler holds nothing yet: has the backend booted?). `--json` prints one document. |
283
+ | `wildo local jobs run <selector>` | Runs that job's ordinary execution once, asynchronously, through the scheduler's manual trigger. Its schedule does not change, and a disabled schedule still runs. The answer means the occurrence was queued for the backend; read its effect where the job writes, a moment later. |
284
+ | `wildo local jobs run <selector> --reason "<why>"` | Records why on the platform audit row every run request leaves. |
285
+
286
+ The selector is application-relative: `<resourceType>.<operation>[:<variantKey>]` for a resource
287
+ operation declared with a cron schedule (the variant may be left out when the operation has one
288
+ schedule), `batch:<ref>` for a custom batch, `minion-tick:<name>` for a minion's tick. Never type the
289
+ platform's job id: the verb resolves the selector against the listing. It refuses a job of another
290
+ application and a job the scheduler no longer holds, and it fails (exit 1) when the run could not be
291
+ queued; it is sent once, never retried, because a re-send could run the job twice.
292
+
293
+ ```bash
294
+ # What is scheduled, and the selectors:
295
+ wildo local jobs
296
+
297
+ # Produce now what an hourly job would write at the top of the hour:
298
+ wildo local jobs run <resourceType>.<operation> --reason "checking what the job writes"
299
+ ```
300
+
275
301
  ### `wildo config sync`
276
302
 
277
303
  Regenerate one or more **generated artifact domains** from the
@@ -186,6 +186,19 @@ export interface BackendDomainModule extends SharedDomainModule {
186
186
  * `capabilities.tools.functionRefs`.
187
187
  */
188
188
  functionTools?: FunctionTool[];
189
+ /**
190
+ * Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
191
+ * connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
192
+ * refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
193
+ */
194
+ mcpServers?: FlowsActors_McpServer[];
195
+ /**
196
+ * Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
197
+ * provider connection whose credential reaches it. Reference them from an agent's
198
+ * `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
199
+ * goes through the outbound guard. See `FlowsActors_RemoteAgent`.
200
+ */
201
+ remoteAgents?: FlowsActors_RemoteAgent[];
189
202
  /**
190
203
  * Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
191
204
  * Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
@@ -594,6 +607,8 @@ function mergeFlowsActors(
594
607
  ) as FlowActorSystem_InitializationFactoryMap,
595
608
  agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
596
609
  functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
610
+ mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
611
+ remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
597
612
  autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
598
613
  chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
599
614
  actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
@@ -115,6 +115,19 @@ one `[dependent-lifecycle-unclassified]` warning. Declare one of four on the edg
115
115
  - `onParentDelete: { enabled: false }` — the rows deliberately outlive their parent
116
116
  intact (evidence of an erasure, for example). Say why in a comment.
117
117
 
118
+ **`mode: LAZY` defers a `DELETE` teardown to the queue.** Use it on an edge whose child set
119
+ only grows (one row per day a recurring item came due, one per event) so that deleting the
120
+ parent does not delete thousands of rows inside the request: the delete enqueues the
121
+ teardown, and the child-teardown job removes the children once the delete has committed,
122
+ re-checking later if it runs first. Until then the children briefly outlive their parent.
123
+ Two limits, both enforced:
124
+
125
+ - A subject erasure whose plan reaches a LAZY edge, at any depth, is REFUSED: an erasure
126
+ cannot wait for a queue. Keep LAZY off any edge an erasure must cross (anything a user
127
+ edge composes). The backend lists every LAZY edge at boot under one
128
+ `[dependent-lifecycle-deferred]` warning.
129
+ - LAZY takes the `DELETE` strategy only. Boot refuses it beside `IMPERSONALIZE_AND_RETAIN`.
130
+
118
131
  Mind `maxDepth` where edges meet: a deeper budget carries a child's own DELETE cascade
119
132
  further down, and can hard-delete rows another edge of the same parent retains.
120
133
 
@@ -471,7 +484,13 @@ when the parent's `recurringType` is `RECURRING`:
471
484
  foreignKeyField: 'todoId',
472
485
  // Static discriminator: only applies when parent todo is RECURRING
473
486
  discriminator: { discriminatorField: todosRecurringTypeField, values: [Todos_RecurrenceType.RECURRING] },
474
- childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.IMMEDIATE, maxDepth: 1 } } },
487
+ // LAZY: a recurring todo gains an occurrence every time it comes due, so a daily todo's set only grows, and deleting
488
+ // it should not delete years of rows inside the request. The delete enqueues the teardown; the child-teardown job
489
+ // removes the occurrences once the delete has committed, and re-checks later if it runs first (#2586). Until then
490
+ // an occurrence may outlive its todo briefly. It is the application's one
491
+ // LAZY edge, so the boot report lists it under [dependent-lifecycle-deferred]. No subject erasure reaches it: no
492
+ // user edge composes a todo or a todo list, and a tenant purge RETAINS todos (the ORGANIZATIONS edge above).
493
+ childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.LAZY, maxDepth: 1 } } },
475
494
  // Only applies to RECURRING todos (Edge Case #2 handled in backend). LIST context is open so the
476
495
  // todo page can list a recurring todo's occurrences (#1787); occurrences declare no SEARCH.
477
496
  contextPolicy: {
@@ -20,12 +20,21 @@ Read and apply these patterns from the application-developer point of view:
20
20
 
21
21
  ## Overview
22
22
 
23
- Backend providers have three packaging homes:
23
+ Backend providers have three packaging homes, and they are tried IN ORDER. Use what the
24
+ framework already has; author a provider only when nothing below fills the need:
24
25
 
25
26
  - **Engine modules** come with the engine's provider package; enabling one needs no separate vendor package.
26
27
  - **Provider modules from the module registry.** `wildo registry add wildo/providers/<ref>` copies the framework's module for one vendor into `providers/<ref>/` and makes it the application's own: its backend part becomes the workspace package `@<your-scope>/provider-<ref>` (`providers/<ref>/backend/`), and its browser part, when it has one, `@<your-scope>/provider-<ref>-frontend` (`providers/<ref>/frontend/`). You own the copy and may edit it; `wildo registry update` keeps and warns about a file you changed instead of overwriting it. `wildo registry search --domain wildo --kind provider` lists the modules on offer; add `--engine-capability <CAPABILITY>` for the ones that fill a capability (`AI_DOCUMENT_EXTRACTION`, say) or `--maturity proven` for the ones that have met the real vendor. A hit that adds operations to another provider says so, and is bound as that provider.
27
28
  - **Separately authored packages** use `@wildo-ai/provider-<ref>` or the application's own scope, for example `@acme/provider-crm`. Any other package — another scope, or an own-scope one not named `provider-*` — is admitted only when the application lists it in `providers.packages`.
28
29
 
30
+ **Author last, and only for a recorded reason.** Before authoring anything, check the engine's
31
+ providers and `wildo registry search --domain wildo --kind provider`. Author a new provider only
32
+ when none of them fills the need (a vendor none offers, a behaviour they lack, or a business
33
+ obligation that names a vendor), and only when that reason is recorded: in a creation run, the
34
+ integration plan's `unprovidedNeeds` entry for the provider's ref; otherwise, in the provider
35
+ package's own README. "It was quicker to write one" is not a reason, and a hand-written copy of a
36
+ registry module is a fork nothing updates.
37
+
29
38
  Discovery reads companion contributions to establish each provider's identity and import path.
30
39
  Runtime scope then decides which hosts may load it. A worker that declares one email sender does
31
40
  not acquire access to every provider just because their packages are installed.
@@ -64,7 +73,9 @@ Never edit the generated artifacts. They are overwritten by every
64
73
  companion in addition to the backend.
65
74
  - Diagnosing a startup refusal that names a provider ref.
66
75
  - Authoring an application-owned provider package under the
67
- application's own npm scope.
76
+ application's own npm scope, ONLY after the engine's providers and the
77
+ registry were checked and offer nothing that fills the need, with the reason
78
+ recorded (see "Author last" above).
68
79
  - Adding operations to a provider another package or the engine owns
69
80
  (an "augmentation", e.g. chat operations on a CRM provider another
70
81
  package ships),
@@ -69,6 +69,8 @@ export const PROVIDER_CAPABILITY_FRONTEND_CONSENT_CLASSIFICATION = Object.freeze
69
69
  SMS: SERVER_ONLY,
70
70
  // #2293: a deliverable is sent for signature from the backend; the vendor's signing page is its own, not a browser SDK.
71
71
  ELECTRONIC_SIGNATURE: SERVER_ONLY,
72
+ // The frame is the application's own engine component, not a browser module the provider loads.
73
+ EMBEDDED_ELECTRONIC_SIGNATURE: SERVER_ONLY,
72
74
  SSO_SAML: SERVER_ONLY,
73
75
  LLM_CHAT: SERVER_ONLY,
74
76
  LLM_EMBEDDINGS: SERVER_ONLY,
@@ -71,6 +71,12 @@ export enum FrontendProviderPublicConfigRefusal {
71
71
  * key is called and whichever vendor the secret belongs to. Never negotiable.
72
72
  */
73
73
  SECRET_VALUE = 'SECRET_VALUE',
74
+ /**
75
+ * A provider contract marks a slot browser-public (`holdsBrowserPublicValue`) whose environment variable is one of the
76
+ * FRAMEWORK's own runtime secrets — a database password, a signing key. The mark would serve that value to every
77
+ * browser, and the backend's value screen cannot see framework secrets, so the contract is refused outright.
78
+ */
79
+ BROWSER_PUBLIC_SLOT_NAMES_FRAMEWORK_SECRET = 'BROWSER_PUBLIC_SLOT_NAMES_FRAMEWORK_SECRET',
74
80
  }
75
81
  ```
76
82
 
@@ -69,6 +69,9 @@ surfaces it serves; `wildo registry search --domain wildo --kind provider`
69
69
  lists the modules. If one exists, install it with
70
70
  `wildo registry add wildo/providers/<ref>` and skip to Step 4: you supply its
71
71
  keys, you do not author it. Read `references/package-frontend-facets.md`.
72
+ Author a module only when neither the engine nor the registry ships the
73
+ vendor's browser part, and record why (in a creation run, the integration
74
+ plan's `unprovidedNeeds` entry for its ref).
72
75
 
73
76
  ### Step 2: Choose the capability and the facet
74
77
 
@@ -65,5 +65,8 @@ never pin it in the module. Publishing refuses a module whose record and facets
65
65
  each service that should run it. A service that does not scope the ref is unaffected.
66
66
  3. Supply the facet's public keys under `providerConfigurations.<ref>.frontend_sdk` — for a Cloudinary picker,
67
67
  `cloudName` and the PUBLIC `apiKey`. Never the API secret: sync refuses any value equal to an environment
68
- secret.
68
+ secret. A key that differs per environment and that the vendor's BACKEND module declares as a secret slot marked
69
+ `holdsBrowserPublicValue` (PostHog's `phc_` project key, slot `apiKey`) needs no entry here: sync serves that
70
+ slot's value from `secrets.json` → `providerEnv` as the facet key of the same name, and an entry here overrides it.
71
+ No other slot is ever read for a browser.
69
72
  4. Run `wildo config sync`, then open the surface. The picker, widget or SDK loads on demand.
@@ -85,7 +85,9 @@ SaaS configuration key, contribution `moduleId` and semantics `relatedModuleId`
85
85
  - Frontend: author a `FrontendModule` containing resource UI behavior, composite views and the
86
86
  intended app-shell contribution. Re-exporting a resources barrel is not a frontend registration.
87
87
  - Backend: author the application-local `BackendOwnedModule` and its `backendModule` contribution.
88
- Follow existing addon wiring for actors and email templates. Labels are engine-owned;
88
+ Follow `backend-addon-wiring` for actors and email templates. A module's emails live in `emails/` and its
89
+ custom operations under `resources/`, never in a folder of your own: `check:module-layout` refuses a module file
90
+ outside its conventional folder (`references/module-scaffold-layout.md` lists them). Labels are engine-owned;
89
91
  do not add a per-module `customLabels` owner or `i18n/` directory.
90
92
  - Specifications: export the named `ModuleBusinessSemantics` value and the applicable resource/view
91
93
  specification maps. This slice does not require a default export.
@@ -135,6 +137,7 @@ Add business-specific operations and UI behavior through their own authoring wor
135
137
  - [ ] Backend discovery sees the emitted default owner and its expected backend contribution.
136
138
  - [ ] The SaaS configuration contains the module binding, separate from source registration.
137
139
  - [ ] Public entrypoints expose the intended shared and specification declarations.
140
+ - [ ] Every conventional module file is in its conventional folder (`check:module-layout`; `emails/`, `resources/`).
138
141
  - [ ] Package checks pass and the relevant running application surface uses the contribution.
139
142
 
140
143
  Locate the standard registration anchors from the application root:
@@ -145,6 +148,8 @@ rg -n 'applicationFrontendModules' frontend/src/modules/index.ts
145
148
  rg -n 'applicationModuleBusinessSemantics' specifications/src/module-registry.specification.ts
146
149
  rg -n 'scanSubdirDefaultExports' backend-api/src/modules/index.ts
147
150
  rg -n 'applicationModules|services' wildo.saas.config.ts
151
+ # A module's email definitions outside emails/ (expect no output; check:module-layout says the same)
152
+ rg -l 'scanEmailTemplateDirectory' backend-api/src/modules | rg -v '/emails/'
148
153
  ```
149
154
 
150
155
  These searches locate owners; inspect list membership and runtime output rather than treating
@@ -157,11 +162,12 @@ matching text as proof of successful loading. For a custom topology, follow its
157
162
  - The backend scanner is edited to add a manual module list.
158
163
  - A running process is checked before the new emitted module has been published.
159
164
  - Empty copied folders, stale exports or a duplicated label owner remain from the reference module.
165
+ - A module's emails sit in `email/` (or any folder but `emails/`), or a resource file sits outside `resources/`: `check:module-layout` fails the task until it is moved.
160
166
 
161
167
  ## References
162
168
 
163
169
  - `references/framework-composition-scenarios-api.md` — complete commands, preview and collision behavior.
164
- - `references/module-scaffold-layout.md` — package layout and explicit registration checklist.
170
+ - `references/module-scaffold-layout.md` — package layout, explicit registration checklist, and the conventional folders `check:module-layout` holds a module to.
165
171
  - `references/framework-new-module-wiring-api.md` — source-backed SaaS and shared module contracts.
166
172
 
167
173
  ## Related Skills
@@ -13,3 +13,20 @@ Declare the module's intended `services` in `wildo.saas.config.ts` as well. This
13
13
  supplies bootstrap topology; it does not insert identifiers into source registries.
14
14
  Use `module-registration` for the canonical loader details. Omit layers that the chosen topology
15
15
  does not need, and do not copy empty directories or invent a per-module label owner.
16
+
17
+ ## Conventional folders inside a module (checked)
18
+
19
+ Some module files are read ONLY at one place, so a file elsewhere compiles and is then silently not read. The build
20
+ lane's `check:module-layout` refuses each of these outside its folder, and its finding is the correction: the move (`mv`)
21
+ and every relative import to update. Put them there from the start; when you meet one elsewhere, move it.
22
+
23
+ | Package | File | Its only place (under `src/modules/<module>/`) | What reads it there |
24
+ |---|---|---|---|
25
+ | `backend-api` | The email definitions file (calls `scanEmailTemplateDirectory`) and its templates | `emails/` (never `email/`, `mail/` or the module root) | The companion's email generation and preview |
26
+ | `backend-api` | Custom operations, `*.operation.ts` | under `resources/` (`resources/<resource>/…`) | `resources/index.ts`, which scans only that folder |
27
+ | `shared-lib` | `<resource>.schemas.ts`, `<resource>.resources-config.ts` | `resources/<resource>/` | The build lane's landed checks |
28
+ | `shared-lib` | `<module>.relationships.ts` | `resources/` | The build lane's landed checks |
29
+ | `frontend` | `<resource>.ui-behavior.tsx` | `resources/<resource>/` | The build lane's landed checks |
30
+ | `specifications` | `<resource>.resource.specification.ts` | `resources/` | The build lane's landed checks |
31
+
32
+ Do not create a second folder of the same kind beside the conventional one (`email/` beside `emails/`).
@@ -35,7 +35,7 @@ declaration a chat could not run.
35
35
 
36
36
  | Surface | Typical path |
37
37
  |---|---|
38
- | The operation's declaration | `shared-lib/src/modules/<module>/<resource>/<resource>.resources-config.ts` |
38
+ | The operation's declaration | `shared-lib/src/modules/<module>/resources/<resource>/<resource>.resources-config.ts` |
39
39
  | The words a command shows (title, field labels, enum values) | your label tree, generated by `wildo generate labels` |
40
40
  | The inbound handler that runs commands | `backend-api/src/**/` (the provider skill's section 8) |
41
41
  | The vendor registration | `wildo providers register <ref>` (Slack manifest, Teams package) |
@@ -377,8 +377,12 @@ condition reads on a SUMMARY row that the row does not carry. The full contract
377
377
  ## A condition says everything its operation refuses
378
378
 
379
379
  `enabledCondition` is not a display hint: the frontend calls it to decide whether to OFFER the action,
380
- and the backend calls it before the operation runs and refuses with 403
381
- `service_resource_operation_disabled` when it is false. So an operation whose handler refuses on the
380
+ and the backend calls it before the operation runs and refuses with
381
+ `service_resource_operation_disabled` when it is false: 409 when the condition read only the row on its
382
+ way to `false` (the row's state forbids it), 403 when it read the caller (`initiatorIds`,
383
+ `initiatorUserContext`) or the request. Write the state check first (`currentObject.status === X &&
384
+ … initiatorIds.userId`), so a refusal on the state never reads the caller and answers 409. So an
385
+ operation whose handler refuses on the
382
386
  row's state ("not while it is a draft") or on who is asking ("not your own request", "only the person
383
387
  who raised it") must say the same in its condition, or the action is offered and then fails. Compare an
384
388
  owner field with `initiatorIds.userId` for the person half, list that field in `enabledConditionFields`,
@@ -54,10 +54,11 @@ operations to a reviewer in these terms rather than as "always audited":
54
54
  |---|---|
55
55
  | A **transactional** operation of your application, called at the top level: one with a `transactionalCore` implementation, a bulk write (`updateMany`, `deleteMany`, …), a token-issuing, token-consuming or token-revoking operation, a create that numbers a document, or a write to an outbound pipeline's destination | **Durable.** The prepared row is kept in the framework's post-commit effect outbox inside the operation's own transaction (with the notifications that go with it) and written right after the commit from there. If the process ends between the commit and the write, the framework's outbox relay writes it later (once at the next startup, then every five minutes), under the id it was prepared with, once. A write that rolls back keeps nothing. Every audited write nested inside that transaction is covered too. One exception: when an effect of that transaction cannot be kept (retiring a SIEM destination, a generated secret), the whole operation is best effort, as the last row describes. |
56
56
  | A verb a framework sweep dispatches (the expiry of organization relationships, professional qualifications and access grants, the lifting of a suspension, an invitation's revocation, a tenant's purge) | **Durable**, the same way, settled by that sweep's next run rather than by the relay, also when someone calls the verb directly. For the purge and the invitation sweep that run is daily, so after a crash such a row can take up to a day to appear. |
57
- | A **plain audited create, update or delete with no custom implementation, or whose every custom implementation declares `hookTransactionPosture: RUNS_INSIDE_TRANSACTION`**, reached through the framework (`API_CALL`, `INTERNAL_CALL`), audited by its declaration (its `riskLevel` is HIGH or CRITICAL, or it sets `auditableEvent.auditBelowRiskFloor`): a single-row `create`, `update` or `delete`, or a custom operation that behaves as one, including one gated by an `enabledCondition` | **Durable**, the same way as a transactional operation: the framework opens a transaction around the write for the sake of its audit row, so the row is kept in the outbox and the relay writes it after a crash. Nothing else changes, because nothing but the framework's own core runs inside that transaction: a delete's cascade already ran in a transaction of its own, removes its children through their repositories, and leaves a file's stored object to the files cleanup batch. A declared implementation's hooks run inside it too, which is why they must do nothing outside the database before the commit (`backend-custom-operation`, `references/framework-hook-transaction-posture-api.md`). A lost race on an `enabledCondition` still answers `409 version_conflict`: the row is re-read in the transaction, and a row that moved since the request was admitted is refused. |
58
- | A **multi-row** `updateMany` / `deleteMany` with no custom implementation and the default response, reached through the framework (`API_CALL`, `INTERNAL_CALL`) and audited by its declaration | **Durable, one chunk at a time.** One transaction holds at most 100 rows (the bound a bulk request already has). A selection within it runs as one transaction, like a single-row write. A larger one runs as consecutive chunks of at most 100 rows, each its own transaction with its own audit row naming its rows: an id list is cut into slices, a filter is walked by `_id`, and your filter still applies to every chunk. So such a write is no longer one atomic statement: when a chunk fails, the chunks before it stay committed and recorded, and the error reaches your code. A custom operation that borrows a multi-row verb and writes the rows itself joins when its implementation declares `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_TRANSACTION`; one whose hook selects an unbounded population stays best effort. |
57
+ | A **plain audited create, update or delete with no custom implementation, or whose every custom implementation declares `hookTransactionPosture: RUNS_INSIDE_TRANSACTION`**, reached through the framework (`API_CALL`, `INTERNAL_CALL`), audited by its declaration (its `riskLevel` is HIGH or CRITICAL, or it sets `auditableEvent.auditBelowRiskFloor`) or by who performed it (an agent's call a human decided, a representative admitted into the organization it writes in): a single-row `create`, `update` or `delete`, or a custom operation that behaves as one, including one gated by an `enabledCondition` | **Durable**, the same way as a transactional operation: the framework opens a transaction around the write for the sake of its audit row, so the row is kept in the outbox and the relay writes it after a crash. Nothing else changes, because nothing but the framework's own core runs inside that transaction: a delete's cascade already ran in a transaction of its own, removes its children through their repositories, and leaves a file's stored object to the files cleanup batch. A declared implementation's hooks run inside it too, which is why they must do nothing outside the database before the commit (`backend-custom-operation`, `references/framework-hook-transaction-posture-api.md`). A lost race on an `enabledCondition` still answers `409 version_conflict`: the row is re-read in the transaction, and a row that moved since the request was admitted is refused. |
58
+ | A **multi-row** `updateMany` / `deleteMany` with no custom implementation and the default response, reached through the framework (`API_CALL`, `INTERNAL_CALL`) and audited by its declaration or by who performed it (an agent's call a human decided, an admitted representative) | **Durable, one chunk at a time.** One transaction holds at most 100 rows (the bound a bulk request already has). A selection within it runs as one transaction, like a single-row write. A larger one runs as consecutive chunks of at most 100 rows, each its own transaction with its own audit row naming its rows: an id list is cut into slices, a filter is walked by `_id`, and your filter still applies to every chunk. So such a write is no longer one atomic statement: when a chunk fails, the chunks before it stay committed and recorded, and the error reaches your code. Because who performed it can make a write audited, the same call above 100 rows is chunked when a representative or a decided agent call performs it and runs as one statement when nobody's presence makes it audited; a client's bulk request is never chunked, whoever sends it. A custom operation that borrows a multi-row verb and writes the rows itself joins when its implementation declares `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_TRANSACTION`. |
59
+ | A **purge whose hook selects a population nothing bounds** (every row of a scope, every row past a cutoff), whose implementation declares `hookTransactionPosture: DELEGATES_WRITES_TO_AUDITED_OPERATIONS` and removes the rows a page at a time through the resource's own `deleteMany` (the engine's SIEM dead-letter `purgeAll` and webhook delivery-log `purgeOld` do; `framework-hook-transaction-posture-api.md` says how) | **Durable for every row removed.** The rows are removed in pages of at most 100, each through the resource's internal `deleteMany`, in its own transaction with its own audit row, as above. The purge's own row is a summary written after the pages, best effort: a crash can lose the summary, never the record of a removal. A row a legal hold covers is kept and counted. |
59
60
  | An engine writer that owns its outbox (`IMPLEMENTATION_OUTBOX`, billing's subscription mutations) | **Durable**, through that writer's own outbox and relay. Reserved for engine writers: an application cannot declare it. |
60
- | Any other audited write called at the top level: a plain create, update or delete with a custom implementation that does not declare `RUNS_INSIDE_TRANSACTION` (undeclared, or `STAYS_OUTSIDE_TRANSACTION` because a hook's answer depends on a provider call or an audit row that must exist first), a multi-row `createMany`, a multi-row write whose implementation selects its own rows without declaring how many one attempt writes, a scheduled (`CRON_JOB`, `BATCH_JOB`) variant, a write audited only because of who performed it (a decided agent proposal, a representative), a write inside a transaction your code opened itself rather than an operation's, and an `OVERRIDE_ALL` implementation | **Best effort.** The row is written right after the commit. A store that refuses the write is logged and counted (`audit_store_failure_total`). A process that ends between the commit and the write loses the row, and nothing counts that loss. When its row must survive a crash, keep the hooks inside the database and declare `RUNS_INSIDE_TRANSACTION`, or give the operation a `transactionalCore` implementation (its hooks then run inside the transaction either way, so keep provider calls out of them). |
61
+ | Any other audited write called at the top level: a plain create, update or delete with a custom implementation that does not declare `RUNS_INSIDE_TRANSACTION` (undeclared, or `STAYS_OUTSIDE_TRANSACTION` because a hook's answer depends on a provider call or an audit row that must exist first), a multi-row `createMany`, a multi-row write whose implementation selects its own rows without declaring how many one attempt writes or delegating them in pages, a scheduled (`CRON_JOB`, `BATCH_JOB`) variant, a write inside a transaction your code opened itself rather than an operation's, and an `OVERRIDE_ALL` implementation | **Best effort.** The row is written right after the commit. A store that refuses the write is logged and counted (`audit_store_failure_total`). A process that ends between the commit and the write loses the row, and nothing counts that loss. When its row must survive a crash, keep the hooks inside the database and declare `RUNS_INSIDE_TRANSACTION`, or give the operation a `transactionalCore` implementation (its hooks then run inside the transaction either way, so keep provider calls out of them). |
61
62
 
62
63
  The durable rows need the outbox in the same database as the operation, which is always the case in an application (it
63
64
  uses one transactional store). A process where it is not says so at startup, per resource.
@@ -1038,6 +1038,21 @@ handler, need no `ec` argument.
1038
1038
  },
1039
1039
  });
1040
1040
  }
1041
+ // #3786: a PERSON is erased through `eraseSubjectAsSystem` only. That door consults both administrative-continuity
1042
+ // floors, takes down the organization only the person lived in, and tears down their dependents; this one scrubs the
1043
+ // row alone and consulted no floor, so a direct scrub of the last owner or super-administrator stranded the tenant or
1044
+ // the application with no refusal and no record. It has no production caller, so the sibling door is closed rather
1045
+ // than given a second copy of the orchestration: an invariant held at one door of two is not held.
1046
+ if (isOrganizationOwnerFloorGovernedSubjectResource(resourceType) || isSuperAdminFloorGovernedSubjectResource(resourceType)) {
1047
+ throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
1048
+ context: {
1049
+ reason: 'person_erased_through_subject_erasure',
1050
+ resourceType,
1051
+ message: `'${String(resourceType)}' rows are people: erase them through eraseSubjectAsSystem, which applies the `
1052
+ + 'administrative-continuity floors, takes down an organization only they belonged to, and tears down their dependents.',
1053
+ },
1054
+ });
1055
+ }
1041
1056
  await this.impersonalizeRowsAsSystem(resourceType, typeof id_or_ids === 'string' ? [id_or_ids] : id_or_ids, options, ExternalDataCopyScrubCause.ERASURE_REQUEST);
1042
1057
  }
1043
1058
 
@@ -1496,13 +1511,26 @@ handler, need no `ec` argument.
1496
1511
  // either, so reporting that first gives the operator the outer problem to solve.
1497
1512
  //
1498
1513
  // Also BEFORE `eraseSubjectInPlace`, so a refusal from either guard leaves nothing written.
1499
- await this.assertOrganizationOwnerFloorForSubjectErasure(
1514
+ const organizationsLeavingWithSubjects = await this.assertOrganizationOwnerFloorForSubjectErasure(
1500
1515
  resourceType,
1501
1516
  subjectIds,
1502
1517
  systemContext,
1503
1518
  options?.acknowledgeOrganizationOwnerFloorBreach,
1504
1519
  );
1505
1520
 
1521
+ // ── The organizations only the subjects lived in go with them (#3786) ──
1522
+ //
1523
+ // The floor refuses stranding, and these strand nobody: the subjects are their last usable owners AND their only
1524
+ // living members, which is the ordinary state of a person who signed up alone. Marked here, after both floors and
1525
+ // before anything of the subjects is written, so a refusal above still leaves nothing written and a failed mark
1526
+ // leaves the subjects untouched. See `takeDownOrganizationsLeavingWithSubjects` for why the outcome is explicit
1527
+ // rather than one transaction.
1528
+ const organizationsTakenDownWithSubject = await this.takeDownOrganizationsLeavingWithSubjects(
1529
+ organizationsLeavingWithSubjects,
1530
+ resourceType,
1531
+ subjectIds,
1532
+ );
1533
+
1506
1534
  // An erasure guard stood here (D6 stance 6c): rows in a system of record refused the erasure until a per-request
1507
1535
  // acknowledgement no request schema could carry. Removed by #2559 (epic #2558): the system of record answers requests
1508
1536
  // about its own records, and each such resource's effect reports HANDLED_AT_SOURCE, naming it, post-commit.
@@ -1523,6 +1551,7 @@ handler, need no `ec` argument.
1523
1551
  const report = await this.getServicesRegistryHandler()
1524
1552
  .getService(resourceType)
1525
1553
  .eraseSubjectInPlace(resourceType, subjectIds, systemContext, options);
1554
+ if (organizationsTakenDownWithSubject.length > 0) report.organizationsTakenDownWithSubject = organizationsTakenDownWithSubject;
1526
1555
 
1527
1556
  // ── External, non-transactional effects — POST-COMMIT by construction ──
1528
1557
  //