@wildo-ai/framework-knowledge 1.1.13 → 1.1.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
- package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +9 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
- package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
- package/dist/knowledge/references/example.config.navigation.full.md +14 -0
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
- package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
- package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
- package/dist/knowledge/references/integration-plan.config.md +78 -8
- package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
- package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
- package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
- package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
- package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
- package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
- package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
- package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
- package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
- package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
- package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +45 -1
- package/dist/knowledge/registries/playbooks.json +2 -2
- package/dist/knowledge/registries/source-tags.json +1175 -1107
- package/dist/knowledge/skills/INDEX.md +2 -2
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
- package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
- package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
- package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
- package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
- package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
- package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
- package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
- package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
- package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
- package/dist/knowledge/topic-index.json +326 -179
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -103,7 +103,7 @@ navigation, design tokens.
|
|
|
103
103
|
| **`config-saas`** — edit `wildo.saas.config.ts` for modules, services, capabilities, and the compliance declarations (operating entity, jurisdictions, retention, AI posture, client storage, provider choices) | "edit wildo.saas.config.ts", "add a module to SaaS config", "wire a new capability at root", "register a service at the app level", "record our legal entity", "declare which jurisdictions we operate in", "set the retention schedule", "who is the data controller" |
|
|
104
104
|
| **`config-saas-backend`** — edit `saas-config.backend.ts`: auth posture, user types, passkey RP, email From, frontend-service login exposure, and how sign-up ASKS for document acceptance | "change the password policy", "enable magic link / MFA / passkeys", "add a user type", "nobody can log in", "authentication_method_not_supported", "set the From address", "how does sign-up ask people to accept the terms", "make people read the terms before signing up", "clickwrap", "we only need a notice beside the button" |
|
|
105
105
|
| **`configure-billing`** — enable billing / make a backend-reachable provider resolve across the 5-surface config chain; write the billing catalogue; record metered usage on an operation, once per case for a price per case | "enable billing", "turn on Stripe", "billing crash-loops the backend", "wire up subscriptions/checkout", "provider not reachable on the backend", "my provider is authored but the backend can't reach it", "bill each case", "record usage when a case closes" |
|
|
106
|
-
| **`provider-backend-package`** — install and scope a BACKEND provider shipped as its own npm package, so a host loads it on demand | "add the Slack provider", "install a provider package", "integrate a vendor on the backend", "my provider package is installed but the backend can't see it", "provider not present in the composed backend catalog", "exports no backendProviderFragment", "how do I ship our own provider" |
|
|
106
|
+
| **`provider-backend-package`** — install and scope a BACKEND provider shipped as its own npm package, so a host loads it on demand; author one only when no engine provider or registry module fills the need, with the reason recorded | "add the Slack provider", "install a provider package", "integrate a vendor on the backend", "my provider package is installed but the backend can't see it", "provider not present in the composed backend catalog", "exports no backendProviderFragment", "how do I ship our own provider" |
|
|
107
107
|
| **`provider-operation-calls`** — call a connected provider's operation from a backend service (generated typed client) or from a frontend component (the browser door, for operations the application declares) | "call the Slack API from my service", "post to a vendor from the backend", "use the generated provider client", "call a provider operation from a component", "my component needs data from a third-party API", "PROVIDER_OPERATION_REFUSED", "not_browser_reachable" |
|
|
108
108
|
| **`provider-frontend-module`** — author or scope a frontend provider module on any browser surface (application, website, docs site): capability, public keys, CSP, scripts, components; including a facet a provider PACKAGE ships on its `./<ref>/frontend-app` subpath | "add a frontend provider", "load a vendor widget in the browser", "use the Cloudinary picker", "ship a browser part in our provider package", "the provider's component never loads", "which keys may a frontend provider take" |
|
|
109
109
|
| **`provider-frontend-file-picker`** — add or tune the frontend FILE PICKER provider (browser-bound module + contribution + scope; framework file fields resolve its constraints automatically); also how ANY provider component loads on the application, the website and the docs site | "add a file picker", "let users attach files", "restrict uploads to PDFs", "raise the upload size limit", "file field accepts anything", "picker allows too many files", "wire a file upload provider", "put a provider component on the website", "show a vendor widget in the docs" |
|
|
@@ -237,7 +237,7 @@ Anything that changes **backend-api code** beyond schema-driven CRUD.
|
|
|
237
237
|
|
|
238
238
|
| Skill | Trigger phrases |
|
|
239
239
|
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
240
|
-
| **`flows-actors-chat-assistant`** **(orchestrator)** — add a conversational AI assistant grounded on resource data (CHAT agent + `resourceReadTool` + FRONTEND actor system + `/flows-actors/:ref` view) | "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "set a deadline on an approval", "remind reviewers before an approval expires", "show the records as cards in the chat" |
|
|
240
|
+
| **`flows-actors-chat-assistant`** **(orchestrator)** — add a conversational AI assistant grounded on resource data (CHAT agent + `resourceReadTool` + FRONTEND actor system + `/flows-actors/:ref` view) | "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "set a deadline on an approval", "remind reviewers before an approval expires", "show the records as cards in the chat", "let my agent call a remote A2A agent" |
|
|
241
241
|
| **`flows-actors-llm-agent-invocation`** — author a ONE-SHOT LLM agent and call it from your own backend code (operation key → agent definition → registration → `invokeAgent` envelope → wrapped output); text or schema-constrained structured output, no conversation and no view | "summarize this with AI", "classify / categorize these with an LLM", "extract fields from this text", "call Claude / GPT from the backend", "add an AI agent that generates X", "get structured JSON out of a model", "score or triage this automatically", "invokeAgent" |
|
|
242
242
|
| **`configure-coding-agent`** — configure the autonomous agent that edits THIS application's own workspace (ACP execution profile → ceiling → host-configuration posture → per-agent limits you cannot configure away) | "set up the coding agent", "let the AI edit my app", "switch to Codex / OpenCode", "use a different model for coding tasks", "the coding agent can't start", "execution profile not found", "my coding run changed nothing", "the agent asked for permission and there was nobody to answer" |
|
|
243
243
|
| **`flows-actors-a2a-exposure`** — expose your agentic actor systems to EXTERNAL AI agents over Agent2Agent (auto-exposed skills + OIDC/OAuth auth; user-delegated OR machine principal → scope-owned conversations) | "expose my actor as an A2A agent", "let other AI agents call my assistant", "agent2agent", "A2A endpoint", "machine / client-credentials access to my chat agent", "how do external agents authenticate to my actor", "agent card" |
|
|
@@ -57,11 +57,14 @@ one typed module record.
|
|
|
57
57
|
| Module DI container | `backend-api/src/modules/<slug>/addons/container.ts` (NOT scaffolded — create it when a module owns injectable services; merged from `backend-api/src/index.ts`) |
|
|
58
58
|
| Module services aggregator | `backend-api/src/modules/<slug>/addons/services/index.ts` |
|
|
59
59
|
| Module controllers aggregator | `backend-api/src/modules/<slug>/addons/controllers/index.ts` |
|
|
60
|
-
| Module email template definitions | `backend-api/src/modules/<slug>/emails/
|
|
60
|
+
| Module email template definitions | `backend-api/src/modules/<slug>/emails/module-email-template-definitions.ts` (scans `resources/`, `system/`) |
|
|
61
|
+
| Module custom operations | `backend-api/src/modules/<slug>/resources/<resource>/*.operation.ts` (any depth under `resources/`; the scan reads nowhere else) |
|
|
61
62
|
| Engine i18n barrel (single owner) | `backend-api/src/engine/i18n/index.ts` (calls `scanCustomLabelsDirectory`) |
|
|
62
63
|
| Module backend registry | `backend-api/src/modules-registry.backend.ts` (`BackendOwnedModule[]`) |
|
|
63
64
|
| `BackendOwnedModule` type | `backend-api/src/backend-owned-module.ts` |
|
|
64
65
|
|
|
66
|
+
**These folders are the rule, not a suggestion.** A module's email definitions and templates live in `emails/` (never `email/` or the module root) and its custom operations under `resources/`: the companion generates and previews a module's emails only under `emails/`, and `resources/index.ts` registers only the operations it scans. The build lane's `check:module-layout` refuses either file elsewhere and states the move (`mv`) and the imports to update.
|
|
67
|
+
|
|
65
68
|
## When to Use
|
|
66
69
|
|
|
67
70
|
- Authoring a new backend module (must wire the
|
|
@@ -214,7 +217,11 @@ const backendModule: BackendDomainModule = {
|
|
|
214
217
|
],
|
|
215
218
|
// A signed webhook from a client's system that creates a todo (#1596) — `POST /webhooks/app/todo-intake`;
|
|
216
219
|
// and an email to an organization's address that creates one and answers on the thread (#1600, #1630).
|
|
217
|
-
|
|
220
|
+
// and what Teams sends the application's bot or an organization's own bot (#2663) — `POST /webhooks/microsoft-teams-bot/messages`.
|
|
221
|
+
inboundHandlers: [todoIntakeInboundHandler, todoEmailIntakeHandler, todoEmailScreenedHandler, todoEmailScreeningHandler, teamsBotInboundHandler],
|
|
222
|
+
// An agent's answer to a Teams conversation goes back through the bot it was sent to; startup refuses the Teams
|
|
223
|
+
// messages handler without it.
|
|
224
|
+
chatReplyHandlers: [teamsChatReplyHandler],
|
|
218
225
|
// NOT listed: `todoSmsStatusHandler` (`./inbound/todos.sms-status.inbound-channel-handler`, #3394), a member's todo
|
|
219
226
|
// status by text. An SMS channel handler stops the backend at startup while the SMS channel does not receive, and
|
|
220
227
|
// Your Application keeps the SMS capability off (no vendor account, 2026-10-02). Enabling SMS with a provider whose
|
package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md
CHANGED
|
@@ -30,6 +30,19 @@ export interface BackendDomainModule extends SharedDomainModule {
|
|
|
30
30
|
* `capabilities.tools.functionRefs`.
|
|
31
31
|
*/
|
|
32
32
|
functionTools?: FunctionTool[];
|
|
33
|
+
/**
|
|
34
|
+
* Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
|
|
35
|
+
* connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
|
|
36
|
+
* refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
|
|
37
|
+
*/
|
|
38
|
+
mcpServers?: FlowsActors_McpServer[];
|
|
39
|
+
/**
|
|
40
|
+
* Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
|
|
41
|
+
* provider connection whose credential reaches it. Reference them from an agent's
|
|
42
|
+
* `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
|
|
43
|
+
* goes through the outbound guard. See `FlowsActors_RemoteAgent`.
|
|
44
|
+
*/
|
|
45
|
+
remoteAgents?: FlowsActors_RemoteAgent[];
|
|
33
46
|
/**
|
|
34
47
|
* Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
|
|
35
48
|
* Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
|
|
@@ -438,6 +451,8 @@ function mergeFlowsActors(
|
|
|
438
451
|
) as FlowActorSystem_InitializationFactoryMap,
|
|
439
452
|
agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
|
|
440
453
|
functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
|
|
454
|
+
mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
|
|
455
|
+
remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
|
|
441
456
|
autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
|
|
442
457
|
chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
|
|
443
458
|
actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
|
|
@@ -27,6 +27,8 @@ hooks. Custom operations are auto-scanned from
|
|
|
27
27
|
`backend-api/src/modules/<slug>/resources/**/*.operation.ts` by
|
|
28
28
|
`scanDefaultExports` and registered through the
|
|
29
29
|
`BackendDomainModule.operations` slot (`backend-addon-wiring`).
|
|
30
|
+
An operation file anywhere else is never registered, and a build task's
|
|
31
|
+
`check:module-layout` refuses it with the move into `resources/<resource>/`.
|
|
30
32
|
|
|
31
33
|
A custom operation file is the spot where:
|
|
32
34
|
|
|
@@ -51,7 +53,7 @@ REPLACE and `overrideAll` have distinct ownership rules described in Step 5.
|
|
|
51
53
|
| Operation auto-scanner | `backend-api/src/modules/<slug>/resources/index.ts` (`scanDefaultExports`) |
|
|
52
54
|
| Operation path types | `@wildo-ai/saas-models` (`CoreResourceOperation`, `ResourceOperationVariantType`) |
|
|
53
55
|
| Custom impl factory + helpers | `@wildo-ai/saas-backend-lib` (`createResourceCustomServiceImplementation`, `ResourcesRegistryBackendService`) |
|
|
54
|
-
| Resource configuration (parity) | `shared-lib/src/modules/<slug>/resources/<resource>/<resource>.
|
|
56
|
+
| Resource configuration (parity) | `shared-lib/src/modules/<slug>/resources/<resource>/<resource>.resources-config.ts` |
|
|
55
57
|
| Repository service | injected via `utils.<resourceRepositoryService>` inside handlers |
|
|
56
58
|
|
|
57
59
|
## When to Use
|
|
@@ -49,16 +49,39 @@ state (it was submitted meanwhile, its budget is closed) names no field: there i
|
|
|
49
49
|
offered. Put the state in the condition (`resource-status-lifecycle`); the engine's own refusal then speaks the
|
|
50
50
|
operation's `unavailableWhen`.
|
|
51
51
|
|
|
52
|
+
## A state the condition already refuses: what arrives, and which rows to write
|
|
53
|
+
|
|
54
|
+
The engine judges `enabledCondition` BEFORE the operation runs. For a condition that reads only the record's state,
|
|
55
|
+
a refusal is a 409 whose `customMessageReference` is `service_resource_operation_disabled`, with no code, and the
|
|
56
|
+
person reads the operation's `unavailableWhen`. A condition that reads the caller (its user, its ids) or the request
|
|
57
|
+
before the state answers 403 for that refusal instead.
|
|
58
|
+
|
|
59
|
+
What the operation's own re-check of that state can then meet depends on WHICH row it reads:
|
|
60
|
+
|
|
61
|
+
- **It reads the row again itself** (an `OVERRIDE_ALL` implementation that fetches the record): a row that moved after
|
|
62
|
+
the request was admitted reaches it, so its code arrives in that race. Declare both: the condition's row first,
|
|
63
|
+
because it is what normally arrives, saying the code arrives only for a row that moved; then the code's row, whose
|
|
64
|
+
`when` stays the sentence the person reads.
|
|
65
|
+
- **It checks the row it was handed** (a prefix or postfix hook on `utils.currentObject`): that is the row the
|
|
66
|
+
condition judged, so the check never sees a moved one. A row that moved is refused by the write's own admission
|
|
67
|
+
precondition, a 409 `version_conflict`. Declare the condition's row and a `version_conflict` row; the code's row may
|
|
68
|
+
stay as a defence, but no HTTP caller normally meets it.
|
|
69
|
+
|
|
70
|
+
A specification that documents only the code tells a client to branch on a code it will almost never receive.
|
|
71
|
+
|
|
52
72
|
## Worked example
|
|
53
73
|
|
|
54
74
|
From a todo application: the codes of one operation, the refusal carrying one, and the specification rows that give
|
|
55
|
-
each code its sentence.
|
|
75
|
+
each code its sentence. The todo's settled state is also the operation's `enabledCondition`, so the rows start with the
|
|
76
|
+
condition's refusal and the code covers the race.
|
|
56
77
|
|
|
57
78
|
|
|
58
79
|
## Usage Example
|
|
59
80
|
|
|
60
81
|
```typescript
|
|
61
82
|
// The person reads the CODE's words (`errors_refusals.<code>.msg`); `reason` and the ids stay for the logs.
|
|
83
|
+
// The operation's `enabledCondition` refuses this state before the operation runs; this re-check is for a todo
|
|
84
|
+
// settled after the request was admitted, read here from the row the operation acts on.
|
|
62
85
|
if (todo.status === Todos_Status.COMPLETED || todo.status === Todos_Status.CANCELLED) {
|
|
63
86
|
throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
|
|
64
87
|
customMessageReference: ErrorCustomMessageReference.RESOURCE_STATUS_TRANSITION_CONFLICT,
|
|
@@ -88,7 +111,11 @@ export enum Todos_AutoResolveRefusalCode {
|
|
|
88
111
|
## Usage Example
|
|
89
112
|
|
|
90
113
|
```typescript
|
|
114
|
+
// A state the operation's `enabledCondition` already refuses arrives as the ENGINE's refusal, before the operation
|
|
115
|
+
// runs: no code, the operation's `unavailableWhen` for words. Document it first, since it is what normally arrives.
|
|
116
|
+
{ code: HttpResponseStatusCode.CONFLICT_409, when: 'The todo is already completed or cancelled: the engine refuses on the operation\'s condition before it runs. ALREADY_SETTLED arrives instead only when the todo was settled after this request was admitted.', customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED },
|
|
91
117
|
// Each code a refusal carries, declared with the sentence the person reads: the labelling pipeline writes it.
|
|
118
|
+
// ALREADY_SETTLED is the operation's own re-check of that state, against a row that moved after admission.
|
|
92
119
|
{ code: HttpResponseStatusCode.CONFLICT_409, errorCode: Todos_AutoResolveRefusalCode.ALREADY_SETTLED, when: 'The todo is already completed or cancelled, so there is nothing left to resolve.' },
|
|
93
120
|
{ code: HttpResponseStatusCode.CONFLICT_409, errorCode: Todos_AutoResolveRefusalCode.ALREADY_RUNNING, when: 'An auto-resolve run for this todo is still open. Wait for it to finish, or answer the approval it is waiting on.' },
|
|
94
121
|
{ code: HttpResponseStatusCode.CONFLICT_409, errorCode: Todos_AutoResolveRefusalCode.NOBODY_TO_TELL, when: 'The todo records no creator and the request did not come from a person, so nobody could be told how the run ended. Start it from a person\'s account.' },
|
|
@@ -47,6 +47,15 @@ short: declare `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_
|
|
|
47
47
|
more by construction (one row by a unique key, a page it bounds itself), and say why. Without it the write stays best
|
|
48
48
|
effort. A multi-row write with no custom implementation needs nothing: the framework runs it 100 rows per transaction.
|
|
49
49
|
|
|
50
|
+
`DELEGATES_WRITES_TO_AUDITED_OPERATIONS` is the posture of a purge whose handler writes nothing itself: it removes a
|
|
51
|
+
population nothing bounds (every row of a scope, every row past a cutoff) a page of at most 100 rows at a time, each
|
|
52
|
+
page through the resource's own declared `deleteMany` with no custom implementation, so each page is its own transaction
|
|
53
|
+
with its own audit row. The framework then never opens a transaction around the handler, and the operation's own audit
|
|
54
|
+
row is a summary written after the pages, best effort. It is accepted only on a REPLACE handler of a multi-row verb
|
|
55
|
+
(`deleteMany`, `updateMany`, or a custom operation borrowing one) without `transactionalCore`. The engine's SIEM
|
|
56
|
+
dead-letter `purgeAll` and webhook delivery-log `purgeOld` are written this way, with an engine-internal page walker that
|
|
57
|
+
applications do not receive; an application purge that wants the same guarantee must page through operations it declares.
|
|
58
|
+
|
|
50
59
|
## Import Origins
|
|
51
60
|
|
|
52
61
|
- `@wildo-ai/saas-backend-lib`
|
|
@@ -80,11 +89,22 @@ effort. A multi-row write with no custom implementation needs nothing: the frame
|
|
|
80
89
|
* provider call, or on an audit row that has to exist before the operation answers), so the write stays best effort,
|
|
81
90
|
* reported under its own reason rather than as unreviewed. Say why at the declaration.
|
|
82
91
|
*
|
|
83
|
-
*
|
|
92
|
+
* DELEGATES_WRITES_TO_AUDITED_OPERATIONS records a third review (#2297): the hooks write nothing themselves. They select a
|
|
93
|
+
* population that nothing bounds (a purge of a whole scope, of every row past a cutoff) and remove it in pages of at most
|
|
94
|
+
* 100 rows, each through a declared operation of the resource (its hook-less internal `DELETE_MANY`), which the framework
|
|
95
|
+
* runs in its own transaction with its own audit row. So every row the operation removes is recorded through a crash, and
|
|
96
|
+
* the answer stays "everything was purged". The operation runs outside any framework transaction (inside one, the
|
|
97
|
+
* delegated writes would join it, unbounded), and its own row is a summary of those writes, written after them, best
|
|
98
|
+
* effort. Accepted only on a REPLACE handler without `transactionalCore`, and honoured only on a multi-row verb
|
|
99
|
+
* (`DELETE_MANY`, `UPDATE_MANY`, or a custom operation borrowing one); elsewhere the write is reported as unreviewed. The
|
|
100
|
+
* engine's purges walk their pages with an engine-internal helper that applications do not receive.
|
|
101
|
+
*
|
|
102
|
+
* A registration with `transactionalCore: true` already runs its hooks in a transaction and needs none of these. Refused beside an
|
|
84
103
|
* `overrideAll` handler, which replaces the pipeline whose transaction this is about.
|
|
85
104
|
*/
|
|
86
105
|
export enum ResourceCustomServiceImplementationHookTransactionPosture {
|
|
87
106
|
RUNS_INSIDE_TRANSACTION = 'runs_inside_transaction',
|
|
88
107
|
STAYS_OUTSIDE_TRANSACTION = 'stays_outside_transaction',
|
|
108
|
+
DELEGATES_WRITES_TO_AUDITED_OPERATIONS = 'delegates_writes_to_audited_operations',
|
|
89
109
|
}
|
|
90
110
|
```
|
|
@@ -307,6 +307,10 @@ actually controls.
|
|
|
307
307
|
one — and `privacy.consentDecidedAt`, stamped by the server when they decide. An empty set WITH an
|
|
308
308
|
instant is "declined everything"; no instant is "never asked". A notice must not state the second
|
|
309
309
|
as the first.
|
|
310
|
+
- per-person `privacy.offeredPurposes` — the purposes a consent surface actually showed the person
|
|
311
|
+
when they decided, accumulated over their decisions. A decision covers only what was shown: when
|
|
312
|
+
the application starts asking for a purpose after someone decided, the consent prompt asks them
|
|
313
|
+
for that purpose alone, and a notice must not describe them as having declined it.
|
|
310
314
|
- `analytics.requiresConsent` (default `true`) — whether the application's analytics rest on
|
|
311
315
|
`ANALYTICS`. It governs analytics alone, never use of the service.
|
|
312
316
|
- the visitor tier: a marketing website keeps a visitor's decision in their browser and starts a
|
|
@@ -606,8 +610,17 @@ region, the places that region processes in, and a `status` (`inside`, `outside`
|
|
|
606
610
|
`no-established-profile`). State the territories from this value, never from prose. `null` means no
|
|
607
611
|
residency is declared: say the service makes no residency commitment rather than naming a region.
|
|
608
612
|
`providers: null` means the providers' profiles were not read, so state the commitment without claiming
|
|
609
|
-
every vendor keeps it. A configuration with any status other than `inside`
|
|
610
|
-
sync`, so a landed application normally shows only
|
|
613
|
+
every vendor keeps it. A configuration with any status other than `inside` or `inside-at-rest` is
|
|
614
|
+
refused by `wildo config sync`, so a landed application normally shows only those two.
|
|
615
|
+
|
|
616
|
+
`storedAtRestTerritories` is a second, weaker promise the operator may opt into: a vendor whose region
|
|
617
|
+
keeps the data in those places and processes it elsewhere. Such a vendor has status `inside-at-rest` and
|
|
618
|
+
carries `storageTerritories`. Name it and say exactly that: the data is stored in those places, and it is
|
|
619
|
+
processed elsewhere. Never write that it processes inside the residency, and never fold it into a sentence
|
|
620
|
+
about the vendors that do. `storedAtRestTerritories: null` means the operator made no such promise.
|
|
621
|
+
When the entry carries a `storageCondition`, the storage holds only on that account arrangement (an add-on, a
|
|
622
|
+
plan, a subuser, data created after residency was set up): state it beside the places, in the vendor's terms,
|
|
623
|
+
so the reader sees what the promise rests on.
|
|
611
624
|
|
|
612
625
|
**Completeness** — do not round any state up.
|
|
613
626
|
|
|
@@ -20,6 +20,12 @@ entity, a sub-processor list, a data processing agreement), each shows the page
|
|
|
20
20
|
read. Open that page, check the fact still holds for YOUR arrangement, and only then write it into
|
|
21
21
|
your entry. The commit is what adopts it; the suggestion is never your answer.
|
|
22
22
|
|
|
23
|
+
When the application relies on a vendor on its at-rest residency (`dataResidency.storedAtRestTerritories`), the
|
|
24
|
+
vendor processes in one place and stores in another. Say both: `processingRegions` where it processes, and
|
|
25
|
+
`storedAtRestIn` where it keeps the data at rest, in your words. The brief suggests the places from the vendor's
|
|
26
|
+
storage map, with the account arrangement they hold on (an add-on, a plan); check that arrangement is yours before
|
|
27
|
+
you write them. Until you do, the international-transfers fact names the vendor in `registerStatesNoStorageFor`.
|
|
28
|
+
|
|
23
29
|
Date the register. `verification: { verifiedAt: 'YYYY-MM-DD', reverificationIntervalDays: N }` records
|
|
24
30
|
when you last checked every entry against the vendors' pages, and how long that check stands (your own
|
|
25
31
|
policy; a yearly supplier review is common). The staleness report (`complianceFactStaleness`) then names
|
|
@@ -297,6 +303,16 @@ const ProcessorIdentityFieldsSchema = z.object({
|
|
|
297
303
|
* `Ireland`, `United States`), and a fixed list would be wrong for the next vendor.
|
|
298
304
|
*/
|
|
299
305
|
processingRegions: z.array(z.string().trim().min(1)).min(1),
|
|
306
|
+
/**
|
|
307
|
+
* Where this processor keeps the data AT REST, when that differs from where it processes it (#3921): a vendor admitted
|
|
308
|
+
* on the application's opt-in at-rest residency stores in one place and processes in another, and a register that
|
|
309
|
+
* named only the processing region could not say the half a reader of the weaker promise needs.
|
|
310
|
+
*
|
|
311
|
+
* In the operator's words, like {@link processingRegions}. The framework SUGGESTS it from the vendor profile's storage
|
|
312
|
+
* map for the chosen region, and the operator adopts it by committing it here, like every other vendor fact (#1744).
|
|
313
|
+
* Absent means not stated; the international-transfers fact names every `inside-at-rest` provider whose entry lacks it.
|
|
314
|
+
*/
|
|
315
|
+
storedAtRestIn: z.array(z.string().trim().min(1)).min(1).optional(),
|
|
300
316
|
/**
|
|
301
317
|
* The processor's own subprocessors.
|
|
302
318
|
*
|