@wildo-ai/framework-knowledge 1.1.12 → 1.1.14
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 +10 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +8 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +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.foundation/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +6 -3
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +9 -0
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +1 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +11 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +14 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +1 -1
- package/dist/knowledge/references/application-maturity.config.md +43 -0
- 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.infra.environment-config.local.md +2 -2
- package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +21 -0
- 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/platform.config.environment.deployment.md +60 -4
- package/dist/knowledge/references/platform.config.infrastructure-host.md +1 -0
- package/dist/knowledge/references/platform.config.platform-key-management.md +5 -2
- package/dist/knowledge/references/requirements.engine-substance.md +38 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +11 -0
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +11 -0
- package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +20 -0
- package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +72 -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.chart-dashboard-view.md +3 -3
- package/dist/knowledge/references/saas.frontend.chart-dashboard.md +38 -35
- package/dist/knowledge/references/saas.models.chart-dashboard-tile-sizes.md +40 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails-environment.md +52 -0
- package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
- package/dist/knowledge/references/saas.models.organization-dashboard-layout.md +61 -0
- package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
- 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.specifications.processor-register.md +10 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +41 -1
- package/dist/knowledge/registries/playbooks.json +1 -1
- package/dist/knowledge/registries/source-tags.json +1147 -1077
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +5 -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 +32 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +11 -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/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-key-management-api.md +58 -1
- package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +20 -3
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +12 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +16 -4
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +144 -6
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +72 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +12 -2
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +12 -2
- package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +1 -1
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +3 -2
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +13 -0
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +36 -8
- package/dist/knowledge/skills/infra-environment-config/references/framework-agent-content-guardrails-environment-api.md +67 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +60 -4
- package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +1 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +5 -2
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +17 -3
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -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 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +21 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
- 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/views-composite-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +166 -39
- 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 +292 -153
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md
CHANGED
|
@@ -3436,6 +3436,19 @@ Dual-thumb slider for numeric intervals.
|
|
|
3436
3436
|
|
|
3437
3437
|
- Preset implementation ships from `@wildo-ai/presets-components`; runtime resolution uses the component registry in `@wildo-ai/saas-frontend-lib`.
|
|
3438
3438
|
|
|
3439
|
+
## `RecordApprovalSeal`
|
|
3440
|
+
|
|
3441
|
+
The electronic approval seal a record stores, shown where the record is read (#2913): who approved it, when, with which meaning and outcome, whether the approval still describes the record, and the approved deliverable's signed copy.
|
|
3442
|
+
|
|
3443
|
+
**Composition**
|
|
3444
|
+
|
|
3445
|
+
- Preset implementation ships from `@wildo-ai/presets-components`; runtime resolution uses the component registry in `@wildo-ai/saas-frontend-lib`.
|
|
3446
|
+
- `RecordApprovalSeal` reads the record and its resource from the display template context and asks `GET /approval-seals/:sealId/records/:resourceType/:resourceId/:field`, admitted by the record's own READ with the reader's credentials and only for the seal the field holds; it asks again when the record changes.
|
|
3447
|
+
- `ApprovalSeal` (the preset contract) is presentational: it draws the view, the moved fields' labels and the action states it is handed, and decides nothing about access.
|
|
3448
|
+
- `FileApprovalSeal fileId` (drawn by `DisplayFieldFile` on a DISPLAY surface) asks `GET /approval-seals/files/:fileId`, admitted by the READ of the record the file belongs to and only for a seal its own record still names; a 404 draws nothing, since most files are attested by nothing. No currency: that is a statement about the approved record.
|
|
3449
|
+
- `DecisionApprovalSeal decisionRef` asks `GET /approval-seals/decisions/:decisionRef`, which answers only the person who decided; it asks again while the seal is pending (signed seconds after the decision). The inbox draws it under the list for decisions answered there, and a conversation's decision card draws it in its own place once answered. It offers no copy: the deliverable is downloaded where its record is read.
|
|
3450
|
+
- Composed from engine components only: Card, Badge, DescriptionList, Alert, Text, Button, Link, Skeleton.
|
|
3451
|
+
|
|
3439
3452
|
## `ResizablePanelGroup`
|
|
3440
3453
|
|
|
3441
3454
|
Let users resize adjacent panels (IDE-style sidebars, preview panes) with persisted layout optional.
|
|
@@ -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
|
|
@@ -487,8 +488,8 @@ export default defineInfraEnvConfig({
|
|
|
487
488
|
* (#2991): its host slot `AZURE_CONTENT_SAFETY_HOST` holds `127.0.0.1:18309` and its key the double's own, both in
|
|
488
489
|
* `secrets.json`, never here. The engine reaches a loopback host only in a development or test environment, so this
|
|
489
490
|
* selection cannot carry the double's address anywhere else. The double is the content-safety simulator of
|
|
490
|
-
* `@wildo-ai/provider-simulators`,
|
|
491
|
-
* answer that their content could not be screened.
|
|
491
|
+
* `@wildo-ai/provider-simulators`, which `wildo local dev` starts on that port with that key; without a service
|
|
492
|
+
* answering there, the guarded agents answer that their content could not be screened or checked.
|
|
492
493
|
*/
|
|
493
494
|
[EngineCapability.AI_CONTENT_SAFETY]: {
|
|
494
495
|
primary: 'azure-content-safety',
|
|
@@ -806,14 +807,17 @@ 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 (the
|
|
813
|
+
broker itself is still provisioned for now; #2303 removes it):
|
|
811
814
|
|
|
812
815
|
| Service the profile drops | Capability it backs | What happens if the application declares the capability anyway |
|
|
813
816
|
|---|---|---|
|
|
814
817
|
| 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
818
|
| 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
819
|
| 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 |
|
|
820
|
+
| 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
821
|
|
|
818
822
|
The refusals are the point. A capability that looks enabled and does
|
|
819
823
|
nothing is worse than one that is refused: an upload certified "clean"
|
|
@@ -964,6 +968,29 @@ provider.
|
|
|
964
968
|
|
|
965
969
|
Read `references/framework-platform-key-management-api.md` for the source-backed contract and the policies.
|
|
966
970
|
|
|
971
|
+
## Agents in an environment without a content classifier
|
|
972
|
+
|
|
973
|
+
An agent that declares `contentGuardrails.promptInjection` or `.outputModeration` refuses every turn in an environment
|
|
974
|
+
where no classifier for that guardrail is present: no `AI_CONTENT_SAFETY` provider is declared, the selected one does
|
|
975
|
+
not offer it (`openai-moderation` does not screen), or its credentials are not authored in that environment's
|
|
976
|
+
`secrets.json → providerEnv`. The classifier is declared once for the application, so leaving its key out of staging is
|
|
977
|
+
how staging runs without it while production has it. To run the agent there anyway, on purpose, the environment says
|
|
978
|
+
so, with why:
|
|
979
|
+
|
|
980
|
+
```ts
|
|
981
|
+
agentContentGuardrails: {
|
|
982
|
+
withoutClassifier: AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED, // from '@wildo-ai/saas-models'
|
|
983
|
+
reason: 'Staging has no Azure Content Safety key; production authors one.',
|
|
984
|
+
},
|
|
985
|
+
```
|
|
986
|
+
|
|
987
|
+
Read `references/framework-agent-content-guardrails-environment-api.md` for the contract. It waives only a guardrail no
|
|
988
|
+
classifier is present for: a classifier that is there and cannot be used (declared and not loaded, a category it does
|
|
989
|
+
not assess) still refuses the turn, and one that fails at call time (a key set and refused, an outage) still withholds
|
|
990
|
+
the output. The backend names each agent it runs unguarded at startup, `wildo local doctor` reports the environment as
|
|
991
|
+
running it unguarded, and outside a local environment `wildo context launch-blockers` lists it. The guardrails
|
|
992
|
+
themselves are the `flows-actors-chat-assistant` skill's.
|
|
993
|
+
|
|
967
994
|
## Running on another application's infrastructure
|
|
968
995
|
|
|
969
996
|
Several applications can share one environment's platform. One application OWNS the
|
|
@@ -1003,6 +1030,7 @@ Read `references/framework-infrastructure-host-api.md` for the source-backed con
|
|
|
1003
1030
|
## References
|
|
1004
1031
|
|
|
1005
1032
|
- `references/framework-infrastructure-host-api.md` — source-backed `infrastructureHost` / hosted descriptor contract
|
|
1033
|
+
- `references/framework-agent-content-guardrails-environment-api.md` — source-backed `agentContentGuardrails`: what the environment does with agents' classifier-backed guardrails when no classifier is selected
|
|
1006
1034
|
- `references/framework-platform-key-management-api.md` — source-backed `platformKeyManagement` contract, the Vault policies and the cloud KMS grants
|
|
1007
1035
|
- `references/framework-application-database-api.md` — source-backed `applicationDatabase` contract
|
|
1008
1036
|
|
|
@@ -1018,7 +1046,7 @@ Read `references/framework-infrastructure-host-api.md` for the source-backed con
|
|
|
1018
1046
|
- [ ] Every backing service the app uses is declared with a valid `source`
|
|
1019
1047
|
- [ ] 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
|
|
1020
1048
|
- [ ] Every capability-required backing service is declared in **every** environment (see "Capability-driven backing services") — `wildo config sync` emits no missing-backing-store warning
|
|
1021
|
-
- [ ] 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
|
|
1049
|
+
- [ ] 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"
|
|
1022
1050
|
- [ ] No secret values in the file (passwords, keys, tokens — all referenced via the secrets store)
|
|
1023
1051
|
- [ ] 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`
|
|
1024
1052
|
- [ ] Local `devCompanion` is optional; remote environments declare `runtimeEnvironment`; remote Kubernetes also requires `remoteProvider`; optional `deployment` matches the chosen workflow
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Framework API: `agentContentGuardrails` (an environment without a content classifier)
|
|
2
|
+
|
|
3
|
+
The source contract for what ONE environment does with its agents' classifier-backed content guardrails
|
|
4
|
+
(`contentGuardrails.promptInjection`, `contentGuardrails.outputModeration`) where no classifier is present for them: it
|
|
5
|
+
declares no provider for `EngineCapability.AI_CONTENT_SAFETY`, the one it selects does not offer the guardrail, or that
|
|
6
|
+
one's credentials are not authored in this environment's `secrets.json → providerEnv`.
|
|
7
|
+
|
|
8
|
+
Read this when:
|
|
9
|
+
|
|
10
|
+
- an agent refuses every turn in staging or production because no classifier is present for its guardrail there (often:
|
|
11
|
+
that environment has no key for it), and running it unguarded there is the decision;
|
|
12
|
+
- `wildo context launch-blockers` lists an environment whose agents run unguarded;
|
|
13
|
+
- the backend's startup log says an agent `RUNS UNGUARDED`.
|
|
14
|
+
|
|
15
|
+
## Import Origins
|
|
16
|
+
|
|
17
|
+
- `@wildo-ai/saas-models`
|
|
18
|
+
|
|
19
|
+
## Source Excerpts
|
|
20
|
+
|
|
21
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
*
|
|
25
|
+
* What an environment does with an agent's classifier-backed content guardrails (`contentGuardrails.promptInjection`,
|
|
26
|
+
* `contentGuardrails.outputModeration`) when NO classifier for the guardrail is present there: its configuration declares
|
|
27
|
+
* no provider for `EngineCapability.AI_CONTENT_SAFETY`, the provider it selects does not offer that guardrail, or that
|
|
28
|
+
* provider's credentials are not authored in this environment's `secrets.json → providerEnv`. Imported
|
|
29
|
+
* from `@wildo-ai/saas-models`; authored as `agentContentGuardrails` in `infrastructure/<env>/wildo.infra.<env>.config.ts`.
|
|
30
|
+
*/
|
|
31
|
+
export enum AgentContentGuardrailsWithoutClassifier {
|
|
32
|
+
/** The default, and what an environment that authors nothing gets: the agent refuses every turn. */
|
|
33
|
+
REFUSE = 'refuse',
|
|
34
|
+
/**
|
|
35
|
+
* The agent runs without each guardrail no classifier is present for here (its tool results unscreened, or its output
|
|
36
|
+
* unmoderated). A classifier that is there and cannot be used is never waived: a declared provider that did not load or
|
|
37
|
+
* a category it does not assess still refuses the turn, and a key that is set and refused, or an outage, still
|
|
38
|
+
* withholds the output. Named at startup, and listed by launch-blockers outside a local environment.
|
|
39
|
+
*/
|
|
40
|
+
RUN_UNGUARDED = 'run_unguarded',
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The environment's declaration. `reason` is required with `RUN_UNGUARDED`: it is printed beside every agent the backend
|
|
45
|
+
* leaves unguarded, so the next reader knows it was decided, and by whom or why.
|
|
46
|
+
*
|
|
47
|
+
* ```ts
|
|
48
|
+
* agentContentGuardrails: {
|
|
49
|
+
* withoutClassifier: AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED,
|
|
50
|
+
* reason: 'Staging has no Azure Content Safety key; production authors one.',
|
|
51
|
+
* },
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
export const EnvironmentAgentContentGuardrailsSchema = z.discriminatedUnion('withoutClassifier', [
|
|
55
|
+
z.strictObject({
|
|
56
|
+
withoutClassifier: z.literal(AgentContentGuardrailsWithoutClassifier.REFUSE),
|
|
57
|
+
}),
|
|
58
|
+
z.strictObject({
|
|
59
|
+
withoutClassifier: z.literal(AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED),
|
|
60
|
+
reason: z.string().trim().min(10, 'Say why this environment runs its agents unguarded (at least 10 characters).').max(500),
|
|
61
|
+
}),
|
|
62
|
+
]);
|
|
63
|
+
export type EnvironmentAgentContentGuardrails = z.output<typeof EnvironmentAgentContentGuardrailsSchema>;
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Authored in `infrastructure/<env>/wildo.infra.<env>.config.ts`, projected by `wildo config sync` to the application
|
|
67
|
+
backend and workers as `WILDO_AGENT_CONTENT_GUARDRAILS`. Absent means `REFUSE`.
|
|
@@ -154,18 +154,25 @@ 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
|
+
* ## The queue
|
|
158
|
+
*
|
|
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
|
+
*
|
|
157
164
|
* ## What it does not change yet
|
|
158
165
|
*
|
|
159
|
-
* The broker
|
|
160
|
-
* application's
|
|
161
|
-
* (`QueueAdapterType.MEMORY` is in-process only). Tracked by #2303.
|
|
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.
|
|
162
168
|
*/
|
|
163
169
|
export enum EnvironmentServiceProfile {
|
|
164
170
|
/** Every service the environment's declarations ask for. The default when nothing is authored. */
|
|
165
171
|
FULL = 'full',
|
|
166
172
|
/**
|
|
167
173
|
* The footprint for a small deployment: no ClamAV, no immudb, no mongot
|
|
168
|
-
* ({@link servicesOmittedByEnvironmentServiceProfile})
|
|
174
|
+
* ({@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
|
|
169
176
|
* (pgvector is part of the PostgreSQL image, not a separate service).
|
|
170
177
|
*/
|
|
171
178
|
SMALL = 'small',
|
|
@@ -221,6 +228,55 @@ export function environmentServiceProfileRunsOneDatabaseFamily(profile: Environm
|
|
|
221
228
|
}
|
|
222
229
|
}
|
|
223
230
|
|
|
231
|
+
/**
|
|
232
|
+
* The queue an environment's application processes share (#2303), as its profile decides it. Total over
|
|
233
|
+
* {@link EnvironmentServiceProfile}: a member added tomorrow fails the build until somebody decides.
|
|
234
|
+
*
|
|
235
|
+
* `FULL` runs RabbitMQ; `SMALL` exists to run without a broker, so its processes share the DATABASE queue, kept in
|
|
236
|
+
* the application's own database (`QueueAdapterType.DATABASE`). Read by the application's container when it binds its
|
|
237
|
+
* queue adapter, so the backend and its minions (which receive the same profile) always choose the same queue.
|
|
238
|
+
*
|
|
239
|
+
* Derived rather than authored: a separate `queueTransport` field beside `serviceProfile` was considered and rejected.
|
|
240
|
+
* `FULL` with the database queue would run a broker nothing uses, and `SMALL` with RabbitMQ would defeat the profile's
|
|
241
|
+
* purpose; neither has a use, and a second field would let them be declared.
|
|
242
|
+
*/
|
|
243
|
+
export function queueAdapterTypeOfEnvironmentServiceProfile(profile: EnvironmentServiceProfile): QueueAdapterType {
|
|
244
|
+
switch (profile) {
|
|
245
|
+
case EnvironmentServiceProfile.FULL:
|
|
246
|
+
return QueueAdapterType.RABBITMQ;
|
|
247
|
+
case EnvironmentServiceProfile.SMALL:
|
|
248
|
+
return QueueAdapterType.DATABASE;
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Why an application that declares minions cannot run under `profile` on `applicationDatabaseEngine`, or undefined when it
|
|
254
|
+
* can (#2303).
|
|
255
|
+
*
|
|
256
|
+
* Under the DATABASE queue a minion takes its ticks from the application's shared queue table, where a plain table grant
|
|
257
|
+
* would let it read and delete every queued job of its application; its RabbitMQ credential is confined to its own
|
|
258
|
+
* queues. On PostgreSQL the same confinement is a row-level security policy (`deriveMinionDatabaseQueueConfinement`,
|
|
259
|
+
* applied through the owed-grants contract), so minions run. MongoDB has no row-level security, so a MongoDB
|
|
260
|
+
* application's minions are refused under that queue, at render and at boot, with the remedy named. Both refusals read
|
|
261
|
+
* this one function.
|
|
262
|
+
*/
|
|
263
|
+
export function describeMinionsRefusedByEnvironmentServiceProfile(
|
|
264
|
+
profile: EnvironmentServiceProfile,
|
|
265
|
+
applicationDatabaseEngine: DatabaseEngine,
|
|
266
|
+
): string | undefined {
|
|
267
|
+
if (queueAdapterTypeOfEnvironmentServiceProfile(profile) !== QueueAdapterType.DATABASE) return undefined;
|
|
268
|
+
switch (applicationDatabaseEngine) {
|
|
269
|
+
case DatabaseEngine.POSTGRESQL:
|
|
270
|
+
return undefined;
|
|
271
|
+
case DatabaseEngine.MONGODB:
|
|
272
|
+
return `This environment runs the '${profile}' service profile (\`serviceProfile\` in wildo.infra.<env>.config.ts), whose `
|
|
273
|
+
+ 'background work runs on the application\'s own database instead of RabbitMQ, and the application persists to '
|
|
274
|
+
+ 'MongoDB, which cannot confine a minion to its own queues there (only PostgreSQL row-level security can). Remove the '
|
|
275
|
+
+ `minions from wildo.saas.config.ts, set applicationDatabase.engine to '${DatabaseEngine.POSTGRESQL}', or set `
|
|
276
|
+
+ `serviceProfile to '${EnvironmentServiceProfile.FULL}'.`;
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
|
|
224
280
|
/** Whether `profile` omits `service`. Absent profile ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}. */
|
|
225
281
|
export function environmentServiceProfileOmits(
|
|
226
282
|
profile: EnvironmentServiceProfile | undefined,
|
|
@@ -84,6 +84,7 @@ export const WildoHostedInfraEnvConfigSchema = z.strictObject({
|
|
|
84
84
|
providerSelection: WILDO_INFRA_ENV_CONFIG_SHAPE.providerSelection,
|
|
85
85
|
providerConfigurations: WILDO_INFRA_ENV_CONFIG_SHAPE.providerConfigurations,
|
|
86
86
|
email: WILDO_INFRA_ENV_CONFIG_SHAPE.email,
|
|
87
|
+
agentContentGuardrails: WILDO_INFRA_ENV_CONFIG_SHAPE.agentContentGuardrails,
|
|
87
88
|
ownershipDnsStandIn: WILDO_INFRA_ENV_CONFIG_SHAPE.ownershipDnsStandIn,
|
|
88
89
|
systemsOfRecord: WILDO_INFRA_ENV_CONFIG_SHAPE.systemsOfRecord,
|
|
89
90
|
documentationSite: WILDO_INFRA_ENV_CONFIG_SHAPE.documentationSite,
|
|
@@ -83,11 +83,14 @@ cloud account for it.
|
|
|
83
83
|
* - Azure Key Vault (a vault in the Azure RBAC permission model): two user-assigned managed identities on apps-manager,
|
|
84
84
|
* each with a CUSTOM role on the vault. The built-in roles do not fit: "Key Vault Crypto User" can update and back up a
|
|
85
85
|
* key, and "Key Vault Crypto Officer" holds `vaults/keys/*`, signing included.
|
|
86
|
-
* - Signer: `Microsoft.KeyVault/vaults/keys/read`, `…/keys/
|
|
86
|
+
* - Signer: `Microsoft.KeyVault/vaults/keys/read`, `…/keys/sign/action`,
|
|
87
87
|
* `…/keys/encrypt/action`, `…/keys/decrypt/action` (a data key is wrapped with A256GCM under an `oct-HSM` key, which
|
|
88
88
|
* a Premium vault offers in preview; a Standard vault cannot hold one and serves signing only).
|
|
89
|
-
* - Operator: `…/keys/read`, `…/keys/
|
|
89
|
+
* - Operator: `…/keys/read`, `…/keys/create/action`, `…/keys/update/action` (disable),
|
|
90
90
|
* `…/keys/delete`, `…/keys/purge/action`.
|
|
91
|
+
* Azure has no `keys/versions/read` data action: `keys/read` reads every version. Measured 2026-11-12 (#3697) with two
|
|
92
|
+
* user-assigned managed identities holding exactly these roles: each verb succeeded as its own identity and answered
|
|
93
|
+
* 403 as the other one.
|
|
91
94
|
* The vault's recovery level decides whether a destroyed key is purged at once or kept until retention ends.
|
|
92
95
|
* - Azure Managed HSM (`*.managedhsm.azure.net`): the same two identities, with custom roles in the HSM's LOCAL RBAC
|
|
93
96
|
* (the built-in "Managed HSM Crypto User" can sign and back up, and cannot purge). Signer:
|
|
@@ -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. */
|
|
@@ -142,9 +142,9 @@ erasure calls. An entry that lists nothing is used for nothing.
|
|
|
142
142
|
**A content-safety classifier in the `companion` scope screens what your
|
|
143
143
|
coding agents read.** While the companion builds the application, a coding
|
|
144
144
|
agent's brief can carry text written outside the repository: market and
|
|
145
|
-
regulatory material a research step gathered from the web. Scope
|
|
146
|
-
|
|
147
|
-
|
|
145
|
+
regulatory material a research step gathered from the web. Scope a classifier
|
|
146
|
+
that SCREENS (`azure-content-safety`; `openai-moderation` moderates output
|
|
147
|
+
only and cannot serve here) under `providers.scopes.companion` with
|
|
148
148
|
`engineCapabilities: [EngineCapability.AI_CONTENT_SAFETY]`, enable
|
|
149
149
|
`AI_CONTENT_SAFETY` in `engineCapabilities`, and set its key with
|
|
150
150
|
`wildo secrets set`. The companion then screens each such element before
|
|
@@ -310,6 +310,20 @@ rather than an API key (Google Vertex AI) declares two more fields:
|
|
|
310
310
|
secrets contract declares, admitted only as an identifier (letters, digits,
|
|
311
311
|
`.`, `_`, `-`), and handed to `sdkFactory` as `context.deploymentParameters`.
|
|
312
312
|
|
|
313
|
+
An LLM or embeddings arm whose vendor authenticates by SIGNING each request
|
|
314
|
+
with IAM credentials (Amazon Bedrock with AWS SigV4) declares `requestSigning`
|
|
315
|
+
INSTEAD of `apiKey`, exactly one of the two:
|
|
316
|
+
|
|
317
|
+
- `requestSigning: { scheme: ProviderRestSigningScheme.AWS_SIGV4, keyIdSecretRef, secretKeySecretRef, sessionTokenSecretRef? }`
|
|
318
|
+
— each a slot your secrets contract declares (the session token only for
|
|
319
|
+
temporary credentials, `required: false`). The engine reads them and calls
|
|
320
|
+
your `sdkFactory` with an empty first argument and the credentials in
|
|
321
|
+
`context.requestSigningCredentials` (`keyId`, `secretKey`, `sessionToken?`,
|
|
322
|
+
`region?`). Pass every value to your SDK client explicitly, so it reads none
|
|
323
|
+
of the process's `AWS_*` variables, and sign for the Region of the host you
|
|
324
|
+
call. A service account cannot sit beside it, and a module declaring both,
|
|
325
|
+
neither, or an undeclared slot is refused at startup.
|
|
326
|
+
|
|
313
327
|
This covers the API calls only. When the same slot also fills an OAuth2
|
|
314
328
|
endpoint host (Workday's `WORKDAY_API_HOST` names its token endpoint too),
|
|
315
329
|
the connect flow refuses a loopback host in every environment, because that
|
|
@@ -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
|
|
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.
|
|
@@ -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,9 +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. |
|
|
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. |
|
|
58
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. |
|
|
59
|
-
| 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
|
|
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). |
|
|
60
62
|
|
|
61
63
|
The durable rows need the outbox in the same database as the operation, which is always the case in an application (it
|
|
62
64
|
uses one transactional store). A process where it is not says so at startup, per resource.
|
|
@@ -102,6 +102,27 @@ type OrganizationEscalationPolicies_CoreOperations =
|
|
|
102
102
|
*/
|
|
103
103
|
dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },
|
|
104
104
|
|
|
105
|
+
/**
|
|
106
|
+
* On a person's Art. 15 export graph: a policy names the person it escalates to (`targetUserId`) and whoever created it
|
|
107
|
+
* (`createdByUserId`), and both foreign keys put it there. Being named as an escalation target, or as a policy's author,
|
|
108
|
+
* is information about that person, so the rows are disclosed, as the module's other member-naming resources are. Until
|
|
109
|
+
* this was declared, the fail-closed export refused every access request of a person this resource can name (the
|
|
110
|
+
* account-erasure-journey lane's download answered 500, #3743).
|
|
111
|
+
*/
|
|
112
|
+
systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
|
|
113
|
+
/**
|
|
114
|
+
* Withheld from every copy: the organization's endpoint, not the person's data, and a webhook URL often carries the
|
|
115
|
+
* credential that authorizes posting to it.
|
|
116
|
+
*/
|
|
117
|
+
subjectExportOthersDataFields: ['webhookUrl'],
|
|
118
|
+
/**
|
|
119
|
+
* Each person's copy withholds the OTHER person the row names: the target's copy does not say who configured the
|
|
120
|
+
* policy, and the author's copy does not say whom it escalates to. An actor's identity is that actor's data.
|
|
121
|
+
*
|
|
122
|
+
* spec-cite: GDPR Art. 15(4) (https://gdpr-info.eu/art-15-gdpr/), as `organizationRepresentativeAssignments` cites it
|
|
123
|
+
*/
|
|
124
|
+
subjectExportOthersDataFieldsByForeignKey: { targetUserId: ['createdByUserId'], createdByUserId: ['targetUserId'] },
|
|
125
|
+
|
|
105
126
|
coreOperations: [
|
|
106
127
|
CoreResourceOperation.READ,
|
|
107
128
|
CoreResourceOperation.LIST,
|
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
|
//
|
|
@@ -120,8 +120,9 @@ What the person sees when a transition is unavailable:
|
|
|
120
120
|
operation's `unavailableWhen` in its specification (`spec-resource-update`). Write that sentence for
|
|
121
121
|
every transition. Give the view `actionVisibility: WHEN_AVAILABLE` in the ui-behavior to hide it
|
|
122
122
|
there too;
|
|
123
|
-
- a call made anyway (an old tab, an API client) is refused by the engine before any hook, as
|
|
124
|
-
`service_resource_operation_disabled
|
|
123
|
+
- a call made anyway (an old tab, an API client) is refused by the engine before any hook, as 409
|
|
124
|
+
`service_resource_operation_disabled` (403 when the condition also read the caller on its way to
|
|
125
|
+
`false`: put the status check first), and the toast speaks the same `unavailableWhen` sentence.
|
|
125
126
|
A refusal the handler raises for any other reason carries a declared code (`backend-custom-operation`).
|
|
126
127
|
|
|
127
128
|
## Worked Example
|
|
@@ -26,10 +26,17 @@ not say is offered and then refused.
|
|
|
26
26
|
*
|
|
27
27
|
* The engine calls `enabledCondition` in TWO places with these parameters, so one function decides both: in the frontend
|
|
28
28
|
* before it offers the action (a list judges each SUMMARY row, a record page the full row), and in the backend before the
|
|
29
|
-
* operation runs, where a `false` refuses the call with
|
|
29
|
+
* operation runs, where a `false` refuses the call with `service_resource_operation_disabled` before any hook. So a
|
|
30
30
|
* condition must say EVERYTHING the operation's handler would refuse on the row's state or on who is asking, or the
|
|
31
31
|
* action is offered and then refused.
|
|
32
32
|
*
|
|
33
|
+
* The refusal's status follows what the condition READ on its way to `false`: only the row (and `objectContext`) is a
|
|
34
|
+
* refusal of the state, 409 Conflict; a read of `initiatorIds`, `initiatorUserContext` or `inputDto` may be a refusal of
|
|
35
|
+
* the caller, 403 Forbidden. `&&` stops at the first false operand, so write the state check FIRST
|
|
36
|
+
* (`currentObject.status === PENDING && currentObject.requestedByUserId !== initiatorIds.userId`): a refusal on the
|
|
37
|
+
* status then never reads the caller and answers 409. On a CREATE-shaped operation `currentObject` is the request body, so
|
|
38
|
+
* a refusal there is never a state conflict: 403.
|
|
39
|
+
*
|
|
33
40
|
* - `currentObject` — the row as it stands. On a list row only its summary fields and the variant's
|
|
34
41
|
* `enabledConditionFields` are present.
|
|
35
42
|
* - `initiatorIds.userId` — the person asking (absent for a machine principal). Compare it with an owner field to offer an
|
package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md
CHANGED
|
@@ -45,7 +45,7 @@ moves the business does not allow.
|
|
|
45
45
|
* read from the row. ACCEPT and DECLINE arriving at the same moment on one SENT quote both pass the
|
|
46
46
|
* condition, but only the first write finds the quote still SENT. The second matches no row and is
|
|
47
47
|
* refused with 409 `version_conflict` (re-read the quote and decide again). One after the other, the second is
|
|
48
|
-
* refused by the condition itself (
|
|
48
|
+
* refused by the condition itself (409 `service_resource_operation_disabled`: it read only the row). Nothing is declared for
|
|
49
49
|
* this: the condition is the declaration.
|
|
50
50
|
*/
|
|
51
51
|
export enum Quote_Status {
|
|
@@ -196,7 +196,7 @@ What each part earns:
|
|
|
196
196
|
`enabledCondition` read from the row (here `status`). ACCEPT and DECLINE arriving together on one SENT
|
|
197
197
|
quote both pass the condition, but only the first write finds the quote still SENT. The second matches no
|
|
198
198
|
row and is refused with 409 `version_conflict` (the answer an `If-Match` conflict gets: re-read the quote
|
|
199
|
-
and decide again), and nothing it would have written lands. One after the other, the second is refused by the condition (
|
|
200
|
-
`service_resource_operation_disabled
|
|
199
|
+
and decide again), and nothing it would have written lands. One after the other, the second is refused by the condition (409
|
|
200
|
+
`service_resource_operation_disabled`, since the condition read only the row). Nothing extra is declared for this, and nothing belongs in
|
|
201
201
|
application code: read the fields the decision depends on in the condition, and they become the write's
|
|
202
202
|
precondition. An edit to a field the condition never read (the title) does not block a transition.
|
|
@@ -482,7 +482,7 @@ const CHANGE_STATUS_ACTION = {
|
|
|
482
482
|
surface: ResourceOperationFrontendSurface.EMBEDDED,
|
|
483
483
|
iconOverride: CircleDot,
|
|
484
484
|
actionPresentation: ResourceOperationActionPresentation.INLINE,
|
|
485
|
-
// Explicit ORDER in the bar. Status is the verb reached for most often on a todo, so it leads;
|
|
485
|
+
// Explicit ORDER in the bar. Status is the verb reached for most often on a todo, so it leads; the move follows (MOVE_TO_LIST, 7).
|
|
486
486
|
// Without this the bar orders by registration, which is an artefact of how the config file was written rather than
|
|
487
487
|
// of how the actions are used — and `actionDisclosure` caps the bar at three, so ordering decides WHICH three survive.
|
|
488
488
|
// Lower comes first, and it must be BELOW 10: that is Edit's default, and every custom operation built on UPDATE
|
|
@@ -649,11 +649,17 @@ const REOPEN_ACTION = {
|
|
|
649
649
|
// foreign key declared to `todoLists`), so "Move to ▾" lists the lists and picking one moves the todo.
|
|
650
650
|
// It is named apart from the route's `todoListId`, the SOURCE list when the todo is opened inside it
|
|
651
651
|
// (see `Todos_MoveToListRequestDto`). It is how a capture leaves the Inbox for its week (#2622).
|
|
652
|
+
//
|
|
653
|
+
// Priority 7, BELOW 10, for CHANGE_STATUS's reason: Edit defaults to 10 and every UPDATE-like custom verb (Make
|
|
654
|
+
// recurring, Unassign…) inherits it, and the detail bar keeps three. At 30 the pick never held a slot: a todo's
|
|
655
|
+
// header read Change status, Edit, Make recurring, and "Move to" sat in the `…` menu, where a DROPDOWN degrades to
|
|
656
|
+
// the overlay form that marks no current list (#3861). Moving is what a todo in the Inbox is opened for, so it
|
|
657
|
+
// takes the slot Make recurring held; it follows the status verbs (5, 6) and leads Edit.
|
|
652
658
|
[Todos_Operations.MOVE_TO_LIST, {
|
|
653
659
|
surface: ResourceOperationFrontendSurface.EMBEDDED,
|
|
654
660
|
iconOverride: FolderInput,
|
|
655
661
|
actionPresentation: ResourceOperationActionPresentation.DROPDOWN,
|
|
656
|
-
displayPriority:
|
|
662
|
+
displayPriority: 7,
|
|
657
663
|
}],
|
|
658
664
|
// These three pair off with ASSIGN and with each other: exactly one of
|
|
659
665
|
// ASSIGN/UNASSIGN applies to a todo, and exactly one of
|