@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.
- package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
- package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +9 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
- package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
- package/dist/knowledge/references/example.config.navigation.full.md +14 -0
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
- package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
- package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
- package/dist/knowledge/references/integration-plan.config.md +78 -8
- package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
- package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
- package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
- package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
- package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
- package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
- package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
- package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
- package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
- package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
- package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +45 -1
- package/dist/knowledge/registries/playbooks.json +2 -2
- package/dist/knowledge/registries/source-tags.json +1175 -1107
- package/dist/knowledge/skills/INDEX.md +2 -2
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
- package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
- package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
- package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
- package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
- package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
- package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
- package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
- package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
- package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
- package/dist/knowledge/topic-index.json +326 -179
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- 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,
|
|
124
|
-
family
|
|
125
|
-
|
|
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
|
|
810
|
-
|
|
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
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
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.
|
|
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,
|
|
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
|
|
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
|
-
* ##
|
|
157
|
+
* ## The queue
|
|
158
158
|
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
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})
|
|
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. */
|
package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md
CHANGED
|
@@ -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
|
package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
381
|
-
`service_resource_operation_disabled` when it is false
|
|
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`,
|
package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md
CHANGED
|
@@ -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
|
|
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
|
|
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.
|
package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md
CHANGED
|
@@ -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
|
//
|