@wildo-ai/framework-knowledge 1.1.14 → 1.1.16

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 (120) 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/creation-state.md +4 -1
  4. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  5. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  6. package/dist/esm/framework-knowledge.definitions.js +13 -0
  7. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  8. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  11. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +6 -4
  13. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  15. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  16. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  17. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  18. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  19. package/dist/knowledge/manifest.json +7 -7
  20. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  21. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  22. package/dist/knowledge/playbooks/bottom_up.build/method.md +10 -8
  23. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  25. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  27. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  28. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  29. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  30. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +4 -0
  31. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  32. package/dist/knowledge/references/backend.inbound-handlers.definition.md +2 -1
  33. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  34. package/dist/knowledge/references/example.electronic-signature.engagement-letter-tool.md +54 -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 +14 -1
  39. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  40. package/dist/knowledge/references/integration-plan.config.md +78 -8
  41. package/dist/knowledge/references/platform.config.environment.deployment.md +27 -4
  42. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  43. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  44. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  45. package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +7 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +16 -0
  47. package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +5 -2
  48. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +19 -0
  49. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  50. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +21 -0
  51. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  52. package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +9 -0
  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.flows.run-state.md +9 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  59. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  60. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  61. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  62. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  63. package/dist/knowledge/registries/framework-topics.json +55 -1
  64. package/dist/knowledge/registries/playbooks.json +2 -2
  65. package/dist/knowledge/registries/source-tags.json +1127 -1042
  66. package/dist/knowledge/skills/INDEX.md +2 -2
  67. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +20 -4
  68. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +4 -1
  69. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  70. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  71. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +4 -0
  72. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  73. package/dist/knowledge/skills/config-app-shell/SKILL.md +4 -0
  74. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +3 -0
  75. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  76. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +69 -19
  77. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  78. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +32 -5
  79. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  80. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  81. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  82. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  83. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  84. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  85. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +35 -3
  86. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  87. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +16 -0
  88. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +30 -0
  89. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  90. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +5 -2
  91. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +207 -0
  92. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +9 -0
  93. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  94. package/dist/knowledge/skills/human-decision-notices/SKILL.md +5 -1
  95. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +9 -0
  96. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +7 -0
  97. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +2 -1
  98. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  99. package/dist/knowledge/skills/infra-environment-config/SKILL.md +31 -9
  100. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +27 -4
  101. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  102. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  103. package/dist/knowledge/skills/module-relationships/SKILL.md +27 -1
  104. package/dist/knowledge/skills/provider-backend-package/SKILL.md +32 -4
  105. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  106. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  107. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  108. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  109. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  110. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  111. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  112. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  113. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  114. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  115. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +21 -0
  116. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -0
  117. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +19 -0
  118. package/dist/knowledge/topic-index.json +295 -114
  119. package/dist/tsconfig.build.tsbuildinfo +1 -1
  120. package/package.json +4 -4
@@ -809,8 +809,10 @@ platform runs. `serviceProfile: EnvironmentServiceProfile.SMALL` (import
809
809
  it from `@wildo-ai/platform-config-lib`) keeps the services the platform
810
810
  cannot run without (one database, the cache and the object store) and
811
811
  drops three optional ones. Its background work (queued jobs, scheduled
812
- batches) runs on the application's own database instead of RabbitMQ (the
813
- broker itself is still provisioned for now; #2303 removes it):
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`:
814
816
 
815
817
  | Service the profile drops | Capability it backs | What happens if the application declares the capability anyway |
816
818
  |---|---|---|
@@ -850,6 +852,10 @@ Rules the descriptor enforces when the file is parsed:
850
852
  - `SMALL` beside `backingServices.clamav` or `.immudb` with
851
853
  `source: SELF` is refused. The two statements contradict each other;
852
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.
853
859
  - `SMALL` with two database families is refused, and the message names
854
860
  the declarations that bring each one in: a second store in
855
861
  `backingServices`, a platform `database.engine` that differs from the
@@ -868,17 +874,33 @@ record that contradicts the profile, for an environment whose
868
874
  `config.json` was written before the profile was authored: run
869
875
  `wildo config sync` after changing the descriptor.
870
876
 
871
- What `SMALL` does not drop yet: **RabbitMQ**. The platform's scheduler
872
- delivers scheduled work to the application's queue from another process,
873
- and no queue that survives a restart runs on the cache or the database
874
- 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.
875
889
 
876
890
  Moving between profiles migrates no data. Going to `SMALL`, the next
877
891
  `wildo local dev` / `wildo local up` stops the dropped containers and
878
- 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
879
895
  from what it kept or from empty: mongot rebuilds its indexes from the
880
- collections, and a new immudb holds no earlier audit history (the
881
- 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.
882
904
 
883
905
  ## Choosing the application's store — and what it obliges
884
906
 
@@ -161,10 +161,12 @@ export function resolveDefaultLocalDataStorage(locationType: WildoLocationType):
161
161
  * HTTP rather than onto a broker. A minion is confined to its own queues there by a PostgreSQL row-level security policy;
162
162
  * MongoDB has none, so a MongoDB application's minions are refused under `SMALL` (`describeMinionsRefusedByEnvironmentServiceProfile`).
163
163
  *
164
- * ## What it does not change yet
164
+ * ## No broker
165
165
  *
166
- * The broker's provisioning: under every profile the environment still runs RabbitMQ and apps-manager still mints the
167
- * application's vhost and credentials, though a `SMALL` application's processes no longer use them. Tracked by #2303.
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.
168
170
  */
169
171
  export enum EnvironmentServiceProfile {
170
172
  /** Every service the environment's declarations ask for. The default when nothing is authored. */
@@ -172,7 +174,7 @@ export enum EnvironmentServiceProfile {
172
174
  /**
173
175
  * The footprint for a small deployment: no ClamAV, no immudb, no mongot
174
176
  * ({@link servicesOmittedByEnvironmentServiceProfile}), one database family, and background work on the application's
175
- * own database instead of RabbitMQ (minions only on PostgreSQL). Vector search remains available on PostgreSQL
177
+ * own database instead of RabbitMQ, which it does not run (minions only on PostgreSQL). Vector search remains available on PostgreSQL
176
178
  * (pgvector is part of the PostgreSQL image, not a separate service).
177
179
  */
178
180
  SMALL = 'small',
@@ -249,6 +251,27 @@ export function queueAdapterTypeOfEnvironmentServiceProfile(profile: Environment
249
251
  }
250
252
  }
251
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
+
252
275
  /**
253
276
  * Why an application that declares minions cannot run under `profile` on `applicationDatabaseEngine`, or undefined when it
254
277
  * can (#2303).
@@ -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
 
@@ -469,9 +482,22 @@ when the parent's `recurringType` is `RECURRING`:
469
482
  {
470
483
  nature: RelationshipNature.COMPOSITION,
471
484
  foreignKeyField: 'todoId',
485
+ // OPTIONAL_CONTEXT, as for tasks: an occurrence is routed under its todo (the todo page lists them) AND directly
486
+ // under its organization, `/organizations/{organizationId}/todos-recurring-occurrences/{todosRecurringOccurrenceId}`.
487
+ // A record shown by id alone needs the second: the Todo Assistant's cards (`presentRecordsTool`) know the
488
+ // organization and the record, never its todo, so with only the nested route a card read "Unavailable" (no
489
+ // endpoint) and opened nothing (#4011). Every occurrence carries its own `organizationId` (the anchor above), so the
490
+ // organization-level route is confined by tenancy like every other organization resource.
491
+ accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
472
492
  // Static discriminator: only applies when parent todo is RECURRING
473
493
  discriminator: { discriminatorField: todosRecurringTypeField, values: [Todos_RecurrenceType.RECURRING] },
474
- childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.IMMEDIATE, maxDepth: 1 } } },
494
+ // LAZY: a recurring todo gains an occurrence every time it comes due, so a daily todo's set only grows, and deleting
495
+ // it should not delete years of rows inside the request. The delete enqueues the teardown; the child-teardown job
496
+ // removes the occurrences once the delete has committed, and re-checks later if it runs first (#2586). Until then
497
+ // an occurrence may outlive its todo briefly. It is the application's one
498
+ // LAZY edge, so the boot report lists it under [dependent-lifecycle-deferred]. No subject erasure reaches it: no
499
+ // user edge composes a todo or a todo list, and a tenant purge RETAINS todos (the ORGANIZATIONS edge above).
500
+ childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.LAZY, maxDepth: 1 } } },
475
501
  // Only applies to RECURRING todos (Edge Case #2 handled in backend). LIST context is open so the
476
502
  // todo page can list a recurring todo's occurrences (#1787); occurrences declare no SEARCH.
477
503
  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),
@@ -329,7 +340,24 @@ endpoint host (Workday's `WORKDAY_API_HOST` names its token endpoint too),
329
340
  the connect flow refuses a loopback host in every environment, because that
330
341
  endpoint is the vendor's `https` host and receives the client secret. A
331
342
  provider whose account is connected through OAuth2 cannot be connected to a
332
- local double this way.
343
+ local double through a host slot.
344
+
345
+ A REST provider with ONE fixed `baseUrl` (Slack's `https://slack.com/api`)
346
+ re-points the whole of it instead: declare `baseUrlOverrideEnvVarName` on the
347
+ REST contract and the same name as a REGISTRATION slot of the secrets
348
+ contract (`SLACK_API_BASE_URL`). In development and test only, a value naming
349
+ a local double (`127.0.0.1:<port>`) sends every operation there with the same
350
+ credential, and the OAuth2 token, revocation and userinfo endpoints written
351
+ under the base follow it, so an e2e lane plays the vendor's Web API and the
352
+ install's code exchange (the `authorizeUrl` is a browser address and stays the
353
+ vendor's: the lane drives the callback itself). Startup refuses it set in any
354
+ other environment, set to anything but a local double, declared beside
355
+ `baseUrlEnvVarName`, `baseUrlHostEnvVarName`, `baseUrlConnectionFact`, a
356
+ templated base or OAuth2 endpoint, `clientCredentials` or `oauth2.audiences`,
357
+ and named by no REGISTRATION slot. Over plain http the double can assert any
358
+ ID-token claim (the engine leaves that signature to TLS), which is why it is a
359
+ development tool only; `wildo local doctor` and `wildo providers probe` still
360
+ call the vendor.
333
361
 
334
362
  There is no other way to re-point a provider. `providerConfigurations` cannot
335
363
  carry `runtimeContract` or `endpoints`: those belong to the provider module,
@@ -857,7 +885,7 @@ disagree with the package.
857
885
  | "The augmentation is installed, so its operations are available." | Nothing applies until `providers.augmentations.<baseRef>` names the package and `wildo config sync` records it; the artifact grep below shows whether it did. |
858
886
  | "I declared `EXTERNAL_ERASURE_OPERATION`, so an erasure reaches the vendor." | Only with a `subjectErasureEffect` on the module AND the application's `subjectReferences`. Without the effect the stance promises a door nobody built; without the references the engine has nothing to erase by. Either way every erasure reads NOT_REGISTERED, unless the operator declared the vendor's own deletion window as the answer instead. |
859
887
  | "I will document the setting and ask the application to call my validation function at boot." | Nothing calls a function an application was asked to call. Declare it as `configurationCheck`: the backend runs it at boot and `wildo local doctor` runs it, both as a WARN, with no application code. |
860
- | "I will override the provider's `runtimeContract.baseUrl` in `providerConfigurations` to reach my local double." | The configuration is refused: the module owns where its key goes. Set the host slot to `127.0.0.1:<port>` in a development environment instead; staging and production refuse it. |
888
+ | "I will override the provider's `runtimeContract.baseUrl` in `providerConfigurations` to reach my local double." | The configuration is refused: the module owns where its key goes. Set the host slot to `127.0.0.1:<port>` in a development environment instead, or, for a fixed base URL, the module's `baseUrlOverrideEnvVarName` variable; staging and production refuse both. |
861
889
  | "Our provider also handles email, so I will give it the email arm." | Composition refuses a non-MAIN provider that declares an engine slot's runtime arm while claiming no capability for it. Declare the capability that names the slot — that is what makes it a deliberate substitution rather than an accident. |
862
890
 
863
891
  ## Red Flags
@@ -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,
@@ -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
 
@@ -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) |
@@ -286,6 +286,34 @@ export const HttpApiFieldMappingSchema = z.strictObject({
286
286
  create: z.string().min(1).optional(),
287
287
  update: z.string().min(1).optional(),
288
288
  }).optional(),
289
+ /**
290
+ * #3953 — WRITE this field through a LOOKUP (Odoo only): a create or update sends `remoteField` of this object instead
291
+ * of the mapping's own `remoteField`, set to the id of the ONE `lookupEntityRef` record whose `lookupRemoteField`
292
+ * equals the value the resource holds. Reads keep the mapping's own `remoteField`.
293
+ *
294
+ * For a field the system of record shows as a code but stores as a reference to another record. On Odoo a partner's
295
+ * `country_code` is the RELATED `country_id.code`: it reads the ISO code, and a write to it is accepted and discarded
296
+ * (measured on Odoo 19.0). The country is written through `country_id`, a many2one to `res.country`:
297
+ *
298
+ * ```ts
299
+ * { localField: 'country', remoteField: 'country_code',
300
+ * writeThrough: { remoteField: 'country_id', lookupEntityRef: 'res.country', lookupRemoteField: 'code' } }
301
+ * ```
302
+ *
303
+ * Each write with a value looks it up once more (one `search_read` on the lookup model, before anything is sent). The
304
+ * match is EXACT and case-sensitive (`'fr'` names no country whose code is `'FR'`), and Odoo leaves archived records
305
+ * of the lookup model out by default. A value no record matches is refused as the caller's
306
+ * (`SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED`); a value several records match, or a `remoteField` that Odoo does not
307
+ * describe as a many2one to `lookupEntityRef`, is refused as the binding's (`SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID`).
308
+ * Nothing is sent either way. An empty value (`null` or `''`) unsets the reference (Odoo's `false`). Refused at
309
+ * registration on any other dialect, on a binding that opens neither create nor update, and when the field it writes is
310
+ * another mapping's field or another write-through's.
311
+ */
312
+ writeThrough: z.strictObject({
313
+ remoteField: z.string().min(1),
314
+ lookupEntityRef: z.string().min(1),
315
+ lookupRemoteField: z.string().min(1),
316
+ }).optional(),
289
317
  });
290
318
  ```
291
319
 
@@ -985,6 +1013,29 @@ export function assertHttpApiBindingDialectCoherence(binding: HttpApiResourceBin
985
1013
  }
986
1014
  }
987
1015
 
1016
+ // #3953 — a write through a lookup is Odoo's (a code shown, a reference stored), and only a write uses it.
1017
+ for (const mapping of binding.fieldMappings) {
1018
+ if (mapping.writeThrough === undefined) continue;
1019
+ const at = `fieldMappings('${mapping.localField}').writeThrough`;
1020
+ if (binding.dialect !== HttpApiTransportDialect.ODOO_JSONRPC && binding.dialect !== HttpApiTransportDialect.ODOO_JSON2) {
1021
+ throw new Error(`${at}: declared on a ${binding.dialect} binding. It resolves a value through a lookup on another Odoo model before a write, and only the Odoo dialects compile one.`);
1022
+ }
1023
+ if (!binding.writableVerbs.includes(HttpApiWriteVerb.CREATE) && !binding.writableVerbs.includes(HttpApiWriteVerb.UPDATE)) {
1024
+ throw new Error(`${at}: this binding opens neither create nor update, so nothing would ever be written through it. Remove it, or open the verb.`);
1025
+ }
1026
+ // Two values for one remote field in one write: whichever is written last would win, silently.
1027
+ const target = mapping.writeThrough.remoteField;
1028
+ const clash = binding.fieldMappings.find((other) => other !== mapping
1029
+ && (other.remoteField === target || other.writeThrough?.remoteField === target));
1030
+ if (clash !== undefined) {
1031
+ throw new Error(`${at}: writes '${target}', which fieldMappings('${clash.localField}') also writes. One remote field takes one value per write.`);
1032
+ }
1033
+ // The population's create values are the engine's (#2552): a create writes them, and the lookup would replace one.
1034
+ if (Object.prototype.hasOwnProperty.call(binding.populationFilter?.createValues ?? {}, target)) {
1035
+ throw new Error(`${at}: writes '${target}', which the population filter's createValues also writes on every create. One remote field takes one value per write.`);
1036
+ }
1037
+ }
1038
+
988
1039
  // #2552 — the population filter: expressible by this dialect's list, and satisfied by what a create writes.
989
1040
  assertHttpApiPopulationFilterCoherence(binding as never);
990
1041
 
@@ -149,13 +149,22 @@ once per pass, however many rows share a second and however a page boundary fall
149
149
  An incremental pass never re-reads a row that did not change in the source. So a change on YOUR side
150
150
  would otherwise reach only rows that happen to change remotely afterwards. The pipeline fingerprints
151
151
  everything that decides what is extracted and how a row is loaded — binding, key fields, the whole
152
- mapping, `sourceFilter`, `archivedRecords`, the partition fields, the operator's partition
153
- ASSIGNMENTS, and the owner organization. When the fingerprint changes, the watermark is dropped and
154
- the next incremental pass reads the whole source once. The run reports
152
+ mapping, `sourceFilter`, the binding's `populationFilter`, `archivedRecords`, the partition fields,
153
+ the operator's partition ASSIGNMENTS, and the owner organization. When the fingerprint changes, the
154
+ watermark is dropped and the next incremental pass reads the whole source once. The run reports
155
155
  `incrementalTrackReset: extraction-basis-changed` (or `no-track` on the first ever pass).
156
156
 
157
- Schedule, `maxRowsPerRun`, `lookbackSeconds`, the orphan policy and the population are NOT in the
158
- fingerprint: they change how often or how carefully rows are read, not what a row holds.
157
+ **The run also names WHAT changed**, in `changedBasisParts` on the run report and on the pipeline
158
+ state's `lastRunSummary`, and in the reset's log line: `source`, `keys`, `mapping`, `source-filter`,
159
+ `population-filter`, `archived-records`, `partition-fields`, `partition-assignments`, `owner`,
160
+ `reference-targets`. Read it before suspecting the pipeline. The common cause of a reset nobody
161
+ expected is `partition-assignments`: an operator assigned, unassigned or moved a partition between
162
+ two runs, and the reset is what makes the newly assigned rows load. The run-history row
163
+ (`wildo context pipelines --runs`) carries only the reason; the parts are on the summary of the last run.
164
+
165
+ Schedule, `maxRowsPerRun`, `lookbackSeconds`, the orphan policy and the destination's `population`
166
+ (`CLOSED` / `OPEN`) are NOT in the fingerprint: they change how often or how carefully rows are read,
167
+ not what a row holds.
159
168
 
160
169
  The FULL pass keys on the same fingerprint. A full pass that spans several runs records the
161
170
  fingerprint it started under, and a run under a different one ABANDONS it and starts a new full pass
@@ -570,6 +570,36 @@ export enum SystemOfRecordErrorCode {
570
570
  */
571
571
  WRITE_FIELD_NOT_WRITABLE = 'SYSTEM_OF_RECORD_WRITE_FIELD_NOT_WRITABLE',
572
572
 
573
+ /**
574
+ * REQUEST — a create or update refused, with a CONFIGURATION error type, because the binding maps a field onto a
575
+ * remote field the system of record COMPUTES and does not store, so a
576
+ * write to it would be accepted and discarded (#3953). Odoo answers `true` to a `create` or `write` naming such a field
577
+ * and keeps nothing: measured on Odoo 19.0, `res.partner.country_code` (related to `country_id.code`) written alone
578
+ * read back `false`. Refused before anything is sent, because the alternative is a write reported as done that changed
579
+ * nothing. The context names the field and, when the system of record says so, the field it is computed from
580
+ * (`computedFrom`), which is the one to write.
581
+ *
582
+ * Not the caller's to fix: the binding's mapping is wrong for writes, so it is a configuration error.
583
+ */
584
+ WRITE_FIELD_COMPUTED_REMOTELY = 'SYSTEM_OF_RECORD_WRITE_FIELD_COMPUTED_REMOTELY',
585
+
586
+ /**
587
+ * REQUEST — a field written through a lookup (`fieldMappings[].writeThrough`, #3953) holds a value no record of the
588
+ * lookup model matches (an ISO country code Odoo does not know, or `'fr'` where the records hold `'FR'`: the match is
589
+ * exact). Refused before anything is sent: writing nothing would report the field as written, and writing a guess
590
+ * would put the row in the wrong place. The context names the field, the lookup model and the value.
591
+ */
592
+ WRITE_VALUE_UNRESOLVED = 'SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED',
593
+
594
+ /**
595
+ * REQUEST — a create or update refused, with a CONFIGURATION error type, because a field's write-through lookup
596
+ * (`fieldMappings[].writeThrough`, #3953) cannot name ONE record: the
597
+ * value matches several records of the lookup model (the lookup field does not identify a record), a match carries no
598
+ * integer id, or the field written is not a many2one to the lookup model as the system of record describes it. The
599
+ * binding's fault, not the caller's; nothing is sent. The context names the field, the lookup model and why.
600
+ */
601
+ WRITE_LOOKUP_INVALID = 'SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID',
602
+
573
603
  /**
574
604
  * REQUEST — the write was SENT and nobody knows whether the system of record applied it: the call
575
605
  * timed out, the connection dropped after the request left, or a gateway answered for the vendor.
@@ -88,3 +88,8 @@ Work down this list; the first two are almost always the answer.
88
88
  5. **A document declaring a shared-secret `token_endpoint_auth_method` is refused.** These clients
89
89
  are public and authenticate with PKCE; a secret would have to be arranged out of band, which
90
90
  defeats the point of the mechanism.
91
+ 6. **A client that is not on your machine cannot reach `http://localhost`**, and some (Claude Desktop)
92
+ refuse a plain-`http` URL outright. `wildo local tunnel up` gives the application a public HTTPS origin
93
+ for the length of a test: the MCP endpoint, the OAuth endpoints and the discovery documents are
94
+ forwarded, nothing else is. Tokens minted before `up` stop working after it. A client that must show
95
+ your consent page in a browser needs the frontend exposed too, which the tunnel does not do yet.
@@ -400,7 +400,9 @@ rather than an instruction to interpret every empty list as an empty knowledge b
400
400
  * return the passage. A passage found only by the lexical arm carries no `vectorRank`, and every
401
401
  * passage in a lexical-only call carries none — which is the expected state when the application
402
402
  * configures no embeddings provider, or when text was committed more recently than the background
403
- * worker has embedded it.
403
+ * worker has embedded it. Such a not-yet-embedded passage is not ranked BELOW embedded ones for that
404
+ * reason alone: when the vector arm ran and could not rank it, its `fusion` counts its lexical rank for
405
+ * both arms, so text written a minute ago competes on its wording from the moment it is committed.
404
406
  *
405
407
  * @example
406
408
  * // Show the strongest passages, and say WHY each was found.
@@ -417,7 +419,7 @@ rather than an instruction to interpret every empty list as an empty knowledge b
417
419
  export interface RagChunkRetrievalScores {
418
420
  /** Reciprocal-rank-fusion score. Ordering key. Not a probability and not comparable across queries. */
419
421
  fusion: number;
420
- /** 1-based rank within the vector arm, absent when that arm did not return this chunk. */
422
+ /** 1-based rank within the vector arm, absent when that arm did not return this chunk (never imputed). */
421
423
  vectorRank?: number;
422
424
  /** Cosine similarity in `[-1, 1]` (`1 - cosine_distance`). Absent with the rank. */
423
425
  vectorSimilarity?: number;
@@ -241,6 +241,18 @@ export enum EngineSettingsDestinationRef {
241
241
  * owner/admin, the roles that bind a client to an agent.
242
242
  */
243
243
  AUTONOMOUS_AGENTS = 'autonomous-agents',
244
+ /**
245
+ * What THIS organization's declared FLOWS and ACTOR SYSTEMS did (#3990): every run on the actor plane, newest first,
246
+ * and each run's history, its tasks (what each actor was asked and produced) and, for a flow, the steps it went
247
+ * through, each with when it happened, in the reader's time zone. Org owner/admin, the people the route admits (an
248
+ * administrator of the organization through an organization-wide role, or the application super-administrator).
249
+ *
250
+ * Beside {@link AGENT_RUNS}, never merged into it: those are CONVERSATIONS (a chat, an A2A client's turn) with their
251
+ * transcripts, read under the execution resource's roles; these are the runs of declared systems, which no resource
252
+ * routes. No capability gate: a flow runs with no language model, so an application declaring flows and no
253
+ * `AI_LLM` still has activity to read; one declaring neither shows an empty list, and may remove the placement.
254
+ */
255
+ AGENT_ACTIVITY = 'agent-activity',
244
256
  /**
245
257
  * Which of the application's chat agents answers the organization's people on each chat connection (#2665): Slack,
246
258
  * Microsoft Teams. Org owner/admin, the roles the `organizationChatSettings` writes accept. A connection with no choice
@@ -370,6 +382,15 @@ export enum EngineSettingsDestinationRef {
370
382
  * application row. What a run consumed is answered to an application cost reader by the run's `usage` operation.
371
383
  */
372
384
  APPLICATION_AGENT_RUNS = 'application-agent-runs',
385
+ /**
386
+ * What the declared flows and actor systems did in EVERY organization (#3990): the same page as
387
+ * {@link AGENT_ACTIVITY}, across tenants, each run naming the organization it worked for. An APPLICATION-WIDE read, so
388
+ * it is admitted under the application's audit read policy (`resolveAuditApplicationReadAccess`): the
389
+ * super-administrator role alone under ROLE_BASED, and a live application access grant a second administrator signed
390
+ * under INDEPENDENT_APPROVAL. Every read is recorded (`PLATFORM_DIRECTORY_ACCESS`, naming the grant when there is one).
391
+ * Super-admin, the role the route admits.
392
+ */
393
+ APPLICATION_AGENT_ACTIVITY = 'application-agent-activity',
373
394
  /**
374
395
  * Which agents the application's super-administrator switched off for EVERY organization (#2843), each with the
375
396
  * justification it was suspended with, and the Suspend and Resume actions. Super-admin, the role both verbs require;
@@ -145,6 +145,11 @@ What earns its place:
145
145
  `sectionRefs` is the **canonical section list** (and MUST match
146
146
  the JSX `<Section name>` set exactly); `operationLike: Op.READ`
147
147
  declares which operation surface this composite is bound to.
148
+ - A composite that renders a chat with the record as its context (`FlowsActorsView` with
149
+ `contextResourceIdentifiers={{ <resourceType>: <id> }}`) also declares
150
+ `conversationSystemRef: '<systemRef>'`: a notice or an email about one of those discussions then opens this
151
+ composite on its record, and the engine hands the discussion to the chat. See the
152
+ `flows-actors-chat-assistant` skill.
148
153
  - The map is typed via `satisfies ResourceCompositeViewsConfig` —
149
154
  preserves exact key types while letting TS validate the shape.
150
155