@wildo-ai/framework-knowledge 1.1.13 → 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.
Files changed (57) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
  4. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
  5. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  6. package/dist/knowledge/manifest.json +3 -3
  7. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  8. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  9. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +11 -2
  10. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  11. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  12. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  13. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  14. package/dist/knowledge/references/example.config.navigation.full.md +14 -0
  15. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  16. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  17. package/dist/knowledge/references/platform.config.environment.deployment.md +60 -4
  18. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  19. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  20. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  21. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
  22. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  23. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  24. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  25. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  26. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  27. package/dist/knowledge/registries/framework-topics.json +1 -1
  28. package/dist/knowledge/registries/playbooks.json +1 -1
  29. package/dist/knowledge/registries/source-tags.json +1038 -1038
  30. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +5 -1
  31. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  32. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
  33. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +11 -2
  34. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  35. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  36. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  37. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  38. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  39. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
  40. package/dist/knowledge/skills/infra-environment-config/SKILL.md +10 -6
  41. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +60 -4
  42. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  43. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  44. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  45. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  46. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
  47. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  48. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  49. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  50. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  51. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  52. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  53. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  54. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  55. package/dist/knowledge/topic-index.json +110 -110
  56. package/dist/tsconfig.build.tsbuildinfo +1 -1
  57. package/package.json +4 -4
@@ -80,6 +80,25 @@ never holds a residency `wildo config sync` would refuse. A provider with severa
80
80
  deployment model to choose, or a region of yours outside is left to you and listed by `wildo context
81
81
  launch-blockers` with the regions that would do; place it, then run the foundation again.
82
82
 
83
+ Many SaaS vendors keep data AT REST in the region you pick but process it elsewhere (support tools, chat,
84
+ document workspaces). Under `territories` alone they are refused. If you are willing to make the weaker promise
85
+ for them, add `storedAtRestTerritories` beside `territories`:
86
+
87
+ ```ts
88
+ operatorComplianceIdentity: {
89
+ dataResidency: { territories: ['eu'], storedAtRestTerritories: ['eu'] },
90
+ },
91
+ ```
92
+
93
+ A vendor whose chosen region processes outside `territories` is then admitted when every place that region keeps
94
+ data at rest, as its provider profile states (`storageRegionTerritories`), lies inside `storedAtRestTerritories`.
95
+ It never counts as inside the processing residency: its entry reads `inside-at-rest`, and the governed documents
96
+ say for it that the data is stored in the region and may be processed elsewhere. A vendor whose profile states no
97
+ storage places is still refused. The foundation keeps the list when it writes `territories`, places a provider on
98
+ it only when none of the provider's regions processes inside, and, when you have declared none, tells you which
99
+ regions declaring one over the same places would admit. It never declares one for you: the promise is yours.
100
+ An organization may narrow both lists, and one that declares no at-rest list admits no storage-only vendor.
101
+
83
102
  To see every part still owed, with the rest of what stands between the application and launch:
84
103
 
85
104
  ```bash
@@ -475,7 +475,7 @@ record of its key, the issuer, and the disclosures the row still holds (the peop
475
475
  statement). Each export is recorded (`approval_seal_exported`); a seal kept after its approver's erasure
476
476
  needs `--operator` and `--justification`. A person's own data export also carries their seals' key
477
477
  records (`verificationKeys`), and leaves out the requester and what was presented, which are other
478
- people's data. Seals are not part of a portability export: the operator made them. To verify a seal, `wildo seal verify <bundle.json>` reads `{ jws, keys, expectedIssuer?, disclosures?, erasedClaims?, deliverableFile?, manifestedCopy? }`, where each key is its stored record (`publishedVerificationKeys`: kid, public JWK,
478
+ people's data. Seals are not part of a portability export: the operator made them. To verify a seal, `wildo seal verify <bundle.json>` reads `{ jws, keys, expectedIssuer?, disclosures?, erasedClaims?, deliverableFile?, manifestedCopy?, vendorSignedCopies? }`, where each key is its stored record (`publishedVerificationKeys`: kid, public JWK,
479
479
  scope, scope id, issuer, state) and calls nothing. It pins ES256 from the key record, ignores any key
480
480
  the token names, refuses an organization key used for another tenant, checks each disclosure against
481
481
  its commitment, and reports content the seal commits to and the bundle does not give without failing
@@ -549,6 +549,20 @@ checks the seal, not the document. A copy that was not made, or is gone, is rebu
549
549
  `wildo seal rebuild-copy <sealId> --justification "…"`, recorded on the audit trail as
550
550
  `approval_seal_manifested_copy_rebuilt`; a seal whose copy is present is refused.
551
551
 
552
+ The same original may also have been signed through an electronic-signature vendor (the
553
+ `ELECTRONIC_SIGNATURE` capability): the vendor's copy is another file derived from it, with lineage role
554
+ `VENDOR_SIGNED_COPY`. A seal's bundle names every such copy of a SIGNED request that followed the seal
555
+ (`vendorSignedCopies`: the file id, the file its row says it derives from, the hash its row recorded).
556
+ `wildo seal verify <bundle.json> --vendor-signed-copy <file>` (repeatable) checks that the copy's first
557
+ revision, ending at a `%%EOF`, is the approved file, and reports which original it derives from. A copy
558
+ whose row names another original, or that does not start with the approved file, fails the seal (and,
559
+ when you call the verifier yourself, so do bytes that are not the ones the row recorded). Only a copy the
560
+ bundle names with these exact bytes is reported as
561
+ the signed copy your application recorded; a file the bundle does not name is reported as starting with
562
+ the approved file and nothing more, since anyone holding the original can append to it. The vendor's own
563
+ signature is not re-checked here: the engine validated it when the signed document arrived, and that
564
+ evidence is the signature request's `validationEvidence` file.
565
+
552
566
  ## Pinning your keys
553
567
 
554
568
  The host holds the keys and publishes their public halves, so on its own your application can only
@@ -120,9 +120,10 @@ export. The typed shape carries:
120
120
  now `source: MANAGED, provider: 'atlas'`
121
121
  - `serviceProfile` (optional) — `EnvironmentServiceProfile.FULL` (the
122
122
  default) or `SMALL`: which optional services the environment runs.
123
- `SMALL` runs no ClamAV, no immudb and no mongot, and one database
124
- family. See "A smaller footprint: `serviceProfile`" below for what
125
- each one costs you
123
+ `SMALL` runs no ClamAV, no immudb and no mongot, one database
124
+ family, and its background work on the application's own database
125
+ (minions only on PostgreSQL). See "A smaller footprint: `serviceProfile`" below
126
+ for what each one costs you
126
127
  - `logging` — `{ level, formattedConsoleErrors }` projected to the
127
128
  process env as `LOG_LEVEL` / `LOG_FORMATTED_CONSOLE_ERRORS` by
128
129
  `env-vars-builder` and consumed at boot by
@@ -806,14 +807,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, the broker and the object
810
- store) and drops three optional ones:
810
+ cannot run without (one database, the cache and the object store) and
811
+ drops three optional ones. Its background work (queued jobs, scheduled
812
+ batches) runs on the application's own database instead of RabbitMQ (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"
@@ -1042,7 +1046,7 @@ Read `references/framework-infrastructure-host-api.md` for the source-backed con
1042
1046
  - [ ] Every backing service the app uses is declared with a valid `source`
1043
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
1044
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
1045
- - [ ] A `SMALL` `serviceProfile` declares no `clamav` / `immudb` with `source: SELF`, runs one database family (one of `mongodb` / `postgresql` in `backingServices`, and `database.engine` equal to `applicationDatabase.engine`), and the application declares none of the capabilities the profile drops (or accepts the boot refusal as the reminder) — see "A smaller footprint"
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"
1046
1050
  - [ ] No secret values in the file (passwords, keys, tokens — all referenced via the secrets store)
1047
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`
1048
1052
  - [ ] Local `devCompanion` is optional; remote environments declare `runtimeEnvironment`; remote Kubernetes also requires `remoteProvider`; optional `deployment` matches the chosen workflow
@@ -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. RabbitMQ stays a platform dependency under every profile: the platform scheduler publishes onto the
160
- * application's queue from another process, and no durable queue runs on the cache or the database
161
- * (`QueueAdapterType.MEMORY` is in-process only). Tracked by #2303.
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}). Vector search remains available on PostgreSQL
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,
@@ -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. */
@@ -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
 
@@ -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 403
381
- `service_resource_operation_disabled` when it is false. So an operation whose handler refuses on the
380
+ and the backend calls it before the operation runs and refuses with
381
+ `service_resource_operation_disabled` when it is false: 409 when the condition read only the row on its
382
+ way to `false` (the row's state forbids it), 403 when it read the caller (`initiatorIds`,
383
+ `initiatorUserContext`) or the request. Write the state check first (`currentObject.status === X &&
384
+ … initiatorIds.userId`), so a refusal on the state never reads the caller and answers 409. So an
385
+ operation whose handler refuses on the
382
386
  row's state ("not while it is a draft") or on who is asking ("not your own request", "only the person
383
387
  who raised it") must say the same in its condition, or the action is offered and then fails. Compare an
384
388
  owner field with `initiatorIds.userId` for the person half, list that field in `enabledConditionFields`,
@@ -54,10 +54,11 @@ operations to a reviewer in these terms rather than as "always audited":
54
54
  |---|---|
55
55
  | A **transactional** operation of your application, called at the top level: one with a `transactionalCore` implementation, a bulk write (`updateMany`, `deleteMany`, …), a token-issuing, token-consuming or token-revoking operation, a create that numbers a document, or a write to an outbound pipeline's destination | **Durable.** The prepared row is kept in the framework's post-commit effect outbox inside the operation's own transaction (with the notifications that go with it) and written right after the commit from there. If the process ends between the commit and the write, the framework's outbox relay writes it later (once at the next startup, then every five minutes), under the id it was prepared with, once. A write that rolls back keeps nothing. Every audited write nested inside that transaction is covered too. One exception: when an effect of that transaction cannot be kept (retiring a SIEM destination, a generated secret), the whole operation is best effort, as the last row describes. |
56
56
  | A verb a framework sweep dispatches (the expiry of organization relationships, professional qualifications and access grants, the lifting of a suspension, an invitation's revocation, a tenant's purge) | **Durable**, the same way, settled by that sweep's next run rather than by the relay, also when someone calls the verb directly. For the purge and the invitation sweep that run is daily, so after a crash such a row can take up to a day to appear. |
57
- | A **plain audited create, update or delete with no custom implementation, or whose every custom implementation declares `hookTransactionPosture: RUNS_INSIDE_TRANSACTION`**, reached through the framework (`API_CALL`, `INTERNAL_CALL`), audited by its declaration (its `riskLevel` is HIGH or CRITICAL, or it sets `auditableEvent.auditBelowRiskFloor`): a single-row `create`, `update` or `delete`, or a custom operation that behaves as one, including one gated by an `enabledCondition` | **Durable**, the same way as a transactional operation: the framework opens a transaction around the write for the sake of its audit row, so the row is kept in the outbox and the relay writes it after a crash. Nothing else changes, because nothing but the framework's own core runs inside that transaction: a delete's cascade already ran in a transaction of its own, removes its children through their repositories, and leaves a file's stored object to the files cleanup batch. A declared implementation's hooks run inside it too, which is why they must do nothing outside the database before the commit (`backend-custom-operation`, `references/framework-hook-transaction-posture-api.md`). A lost race on an `enabledCondition` still answers `409 version_conflict`: the row is re-read in the transaction, and a row that moved since the request was admitted is refused. |
58
- | A **multi-row** `updateMany` / `deleteMany` with no custom implementation and the default response, reached through the framework (`API_CALL`, `INTERNAL_CALL`) and audited by its declaration | **Durable, one chunk at a time.** One transaction holds at most 100 rows (the bound a bulk request already has). A selection within it runs as one transaction, like a single-row write. A larger one runs as consecutive chunks of at most 100 rows, each its own transaction with its own audit row naming its rows: an id list is cut into slices, a filter is walked by `_id`, and your filter still applies to every chunk. So such a write is no longer one atomic statement: when a chunk fails, the chunks before it stay committed and recorded, and the error reaches your code. A custom operation that borrows a multi-row verb and writes the rows itself joins when its implementation declares `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_TRANSACTION`; one whose hook selects an unbounded population stays best effort. |
57
+ | A **plain audited create, update or delete with no custom implementation, or whose every custom implementation declares `hookTransactionPosture: RUNS_INSIDE_TRANSACTION`**, reached through the framework (`API_CALL`, `INTERNAL_CALL`), audited by its declaration (its `riskLevel` is HIGH or CRITICAL, or it sets `auditableEvent.auditBelowRiskFloor`) or by who performed it (an agent's call a human decided, a representative admitted into the organization it writes in): a single-row `create`, `update` or `delete`, or a custom operation that behaves as one, including one gated by an `enabledCondition` | **Durable**, the same way as a transactional operation: the framework opens a transaction around the write for the sake of its audit row, so the row is kept in the outbox and the relay writes it after a crash. Nothing else changes, because nothing but the framework's own core runs inside that transaction: a delete's cascade already ran in a transaction of its own, removes its children through their repositories, and leaves a file's stored object to the files cleanup batch. A declared implementation's hooks run inside it too, which is why they must do nothing outside the database before the commit (`backend-custom-operation`, `references/framework-hook-transaction-posture-api.md`). A lost race on an `enabledCondition` still answers `409 version_conflict`: the row is re-read in the transaction, and a row that moved since the request was admitted is refused. |
58
+ | A **multi-row** `updateMany` / `deleteMany` with no custom implementation and the default response, reached through the framework (`API_CALL`, `INTERNAL_CALL`) and audited by its declaration or by who performed it (an agent's call a human decided, an admitted representative) | **Durable, one chunk at a time.** One transaction holds at most 100 rows (the bound a bulk request already has). A selection within it runs as one transaction, like a single-row write. A larger one runs as consecutive chunks of at most 100 rows, each its own transaction with its own audit row naming its rows: an id list is cut into slices, a filter is walked by `_id`, and your filter still applies to every chunk. So such a write is no longer one atomic statement: when a chunk fails, the chunks before it stay committed and recorded, and the error reaches your code. Because who performed it can make a write audited, the same call above 100 rows is chunked when a representative or a decided agent call performs it and runs as one statement when nobody's presence makes it audited; a client's bulk request is never chunked, whoever sends it. A custom operation that borrows a multi-row verb and writes the rows itself joins when its implementation declares `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_TRANSACTION`. |
59
+ | A **purge whose hook selects a population nothing bounds** (every row of a scope, every row past a cutoff), whose implementation declares `hookTransactionPosture: DELEGATES_WRITES_TO_AUDITED_OPERATIONS` and removes the rows a page at a time through the resource's own `deleteMany` (the engine's SIEM dead-letter `purgeAll` and webhook delivery-log `purgeOld` do; `framework-hook-transaction-posture-api.md` says how) | **Durable for every row removed.** The rows are removed in pages of at most 100, each through the resource's internal `deleteMany`, in its own transaction with its own audit row, as above. The purge's own row is a summary written after the pages, best effort: a crash can lose the summary, never the record of a removal. A row a legal hold covers is kept and counted. |
59
60
  | An engine writer that owns its outbox (`IMPLEMENTATION_OUTBOX`, billing's subscription mutations) | **Durable**, through that writer's own outbox and relay. Reserved for engine writers: an application cannot declare it. |
60
- | Any other audited write called at the top level: a plain create, update or delete with a custom implementation that does not declare `RUNS_INSIDE_TRANSACTION` (undeclared, or `STAYS_OUTSIDE_TRANSACTION` because a hook's answer depends on a provider call or an audit row that must exist first), a multi-row `createMany`, a multi-row write whose implementation selects its own rows without declaring how many one attempt writes, a scheduled (`CRON_JOB`, `BATCH_JOB`) variant, a write audited only because of who performed it (a decided agent proposal, a representative), a write inside a transaction your code opened itself rather than an operation's, and an `OVERRIDE_ALL` implementation | **Best effort.** The row is written right after the commit. A store that refuses the write is logged and counted (`audit_store_failure_total`). A process that ends between the commit and the write loses the row, and nothing counts that loss. When its row must survive a crash, keep the hooks inside the database and declare `RUNS_INSIDE_TRANSACTION`, or give the operation a `transactionalCore` implementation (its hooks then run inside the transaction either way, so keep provider calls out of them). |
61
+ | Any other audited write called at the top level: a plain create, update or delete with a custom implementation that does not declare `RUNS_INSIDE_TRANSACTION` (undeclared, or `STAYS_OUTSIDE_TRANSACTION` because a hook's answer depends on a provider call or an audit row that must exist first), a multi-row `createMany`, a multi-row write whose implementation selects its own rows without declaring how many one attempt writes or delegating them in pages, a scheduled (`CRON_JOB`, `BATCH_JOB`) variant, a write inside a transaction your code opened itself rather than an operation's, and an `OVERRIDE_ALL` implementation | **Best effort.** The row is written right after the commit. A store that refuses the write is logged and counted (`audit_store_failure_total`). A process that ends between the commit and the write loses the row, and nothing counts that loss. When its row must survive a crash, keep the hooks inside the database and declare `RUNS_INSIDE_TRANSACTION`, or give the operation a `transactionalCore` implementation (its hooks then run inside the transaction either way, so keep provider calls out of them). |
61
62
 
62
63
  The durable rows need the outbox in the same database as the operation, which is always the case in an application (it
63
64
  uses one transactional store). A process where it is not says so at startup, per resource.
@@ -1038,6 +1038,21 @@ handler, need no `ec` argument.
1038
1038
  },
1039
1039
  });
1040
1040
  }
1041
+ // #3786: a PERSON is erased through `eraseSubjectAsSystem` only. That door consults both administrative-continuity
1042
+ // floors, takes down the organization only the person lived in, and tears down their dependents; this one scrubs the
1043
+ // row alone and consulted no floor, so a direct scrub of the last owner or super-administrator stranded the tenant or
1044
+ // the application with no refusal and no record. It has no production caller, so the sibling door is closed rather
1045
+ // than given a second copy of the orchestration: an invariant held at one door of two is not held.
1046
+ if (isOrganizationOwnerFloorGovernedSubjectResource(resourceType) || isSuperAdminFloorGovernedSubjectResource(resourceType)) {
1047
+ throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
1048
+ context: {
1049
+ reason: 'person_erased_through_subject_erasure',
1050
+ resourceType,
1051
+ message: `'${String(resourceType)}' rows are people: erase them through eraseSubjectAsSystem, which applies the `
1052
+ + 'administrative-continuity floors, takes down an organization only they belonged to, and tears down their dependents.',
1053
+ },
1054
+ });
1055
+ }
1041
1056
  await this.impersonalizeRowsAsSystem(resourceType, typeof id_or_ids === 'string' ? [id_or_ids] : id_or_ids, options, ExternalDataCopyScrubCause.ERASURE_REQUEST);
1042
1057
  }
1043
1058
 
@@ -1496,13 +1511,26 @@ handler, need no `ec` argument.
1496
1511
  // either, so reporting that first gives the operator the outer problem to solve.
1497
1512
  //
1498
1513
  // Also BEFORE `eraseSubjectInPlace`, so a refusal from either guard leaves nothing written.
1499
- await this.assertOrganizationOwnerFloorForSubjectErasure(
1514
+ const organizationsLeavingWithSubjects = await this.assertOrganizationOwnerFloorForSubjectErasure(
1500
1515
  resourceType,
1501
1516
  subjectIds,
1502
1517
  systemContext,
1503
1518
  options?.acknowledgeOrganizationOwnerFloorBreach,
1504
1519
  );
1505
1520
 
1521
+ // ── The organizations only the subjects lived in go with them (#3786) ──
1522
+ //
1523
+ // The floor refuses stranding, and these strand nobody: the subjects are their last usable owners AND their only
1524
+ // living members, which is the ordinary state of a person who signed up alone. Marked here, after both floors and
1525
+ // before anything of the subjects is written, so a refusal above still leaves nothing written and a failed mark
1526
+ // leaves the subjects untouched. See `takeDownOrganizationsLeavingWithSubjects` for why the outcome is explicit
1527
+ // rather than one transaction.
1528
+ const organizationsTakenDownWithSubject = await this.takeDownOrganizationsLeavingWithSubjects(
1529
+ organizationsLeavingWithSubjects,
1530
+ resourceType,
1531
+ subjectIds,
1532
+ );
1533
+
1506
1534
  // An erasure guard stood here (D6 stance 6c): rows in a system of record refused the erasure until a per-request
1507
1535
  // acknowledgement no request schema could carry. Removed by #2559 (epic #2558): the system of record answers requests
1508
1536
  // about its own records, and each such resource's effect reports HANDLED_AT_SOURCE, naming it, post-commit.
@@ -1523,6 +1551,7 @@ handler, need no `ec` argument.
1523
1551
  const report = await this.getServicesRegistryHandler()
1524
1552
  .getService(resourceType)
1525
1553
  .eraseSubjectInPlace(resourceType, subjectIds, systemContext, options);
1554
+ if (organizationsTakenDownWithSubject.length > 0) report.organizationsTakenDownWithSubject = organizationsTakenDownWithSubject;
1526
1555
 
1527
1556
  // ── External, non-transactional effects — POST-COMMIT by construction ──
1528
1557
  //
@@ -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 403
124
- `service_resource_operation_disabled`, and the toast speaks the same `unavailableWhen` sentence.
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 403 `service_resource_operation_disabled` before any hook. So a
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
@@ -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 (403 `service_resource_operation_disabled`). Nothing is declared for
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 (403
200
- `service_resource_operation_disabled`). Nothing extra is declared for this, and nothing belongs in
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; assignment follows.
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: 30,
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
@@ -138,7 +138,11 @@ const backendModule: BackendDomainModule = {
138
138
  ],
139
139
  // A signed webhook from a client's system that creates a todo (#1596) — `POST /webhooks/app/todo-intake`;
140
140
  // and an email to an organization's address that creates one and answers on the thread (#1600, #1630).
141
- inboundHandlers: [todoIntakeInboundHandler, todoEmailIntakeHandler, todoEmailScreenedHandler, todoEmailScreeningHandler],
141
+ // and what Teams sends the application's bot or an organization's own bot (#2663) — `POST /webhooks/microsoft-teams-bot/messages`.
142
+ inboundHandlers: [todoIntakeInboundHandler, todoEmailIntakeHandler, todoEmailScreenedHandler, todoEmailScreeningHandler, teamsBotInboundHandler],
143
+ // An agent's answer to a Teams conversation goes back through the bot it was sent to; startup refuses the Teams
144
+ // messages handler without it.
145
+ chatReplyHandlers: [teamsChatReplyHandler],
142
146
  // NOT listed: `todoSmsStatusHandler` (`./inbound/todos.sms-status.inbound-channel-handler`, #3394), a member's todo
143
147
  // status by text. An SMS channel handler stops the backend at startup while the SMS channel does not receive, and
144
148
  // Your Application keeps the SMS capability off (no vendor account, 2026-10-02). Enabling SMS with a provider whose
@@ -323,6 +323,12 @@ const ALLOWED_BARE_SPECIFIERS: ReadonlySet<string> = new Set([
323
323
  */
324
324
  'node:module',
325
325
  'node:url',
326
+ /**
327
+ * `node:crypto` — `websiteContentSecurityPolicy()` (`content-security-policy.integration.ts`, on the `astro.ts`
328
+ * sub-entry, #3830) names each inline script it moves out of a built page by the SHA-256 of its content. It runs in
329
+ * `astro.config.ts` after the build, never in an island; pinned SSR-only below.
330
+ */
331
+ 'node:crypto',
326
332
  /**
327
333
  * `sharp` — measures a blog post's cover from the site's `public/` at build time (`blog-post-cover.resolver.ts`, on
328
334
  * the `astro.ts` sub-entry, #2723), so a cover reaches `WebsiteImage` with its real size. A native library: loaded
@@ -256,6 +256,12 @@ const ALLOWED_BARE_SPECIFIERS: ReadonlySet<string> = new Set([
256
256
  */
257
257
  'node:module',
258
258
  'node:url',
259
+ /**
260
+ * `node:crypto` — `websiteContentSecurityPolicy()` (`content-security-policy.integration.ts`, on the `astro.ts`
261
+ * sub-entry, #3830) names each inline script it moves out of a built page by the SHA-256 of its content. It runs in
262
+ * `astro.config.ts` after the build, never in an island; pinned SSR-only below.
263
+ */
264
+ 'node:crypto',
259
265
  /**
260
266
  * `sharp` — measures a blog post's cover from the site's `public/` at build time (`blog-post-cover.resolver.ts`, on
261
267
  * the `astro.ts` sub-entry, #2723), so a cover reaches `WebsiteImage` with its real size. A native library: loaded