@wildo-ai/framework-knowledge 1.1.14 → 1.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +4 -1
  4. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  5. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  6. package/dist/esm/framework-knowledge.definitions.js +13 -0
  7. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  8. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  11. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +6 -4
  13. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  15. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  16. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  17. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  18. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  19. package/dist/knowledge/manifest.json +7 -7
  20. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  21. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  22. package/dist/knowledge/playbooks/bottom_up.build/method.md +10 -8
  23. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  25. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  27. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  28. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  29. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  30. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +4 -0
  31. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  32. package/dist/knowledge/references/backend.inbound-handlers.definition.md +2 -1
  33. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  34. package/dist/knowledge/references/example.electronic-signature.engagement-letter-tool.md +54 -0
  35. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
  36. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
  37. package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
  38. package/dist/knowledge/references/example.module.relationships.discriminator.md +14 -1
  39. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  40. package/dist/knowledge/references/integration-plan.config.md +78 -8
  41. package/dist/knowledge/references/platform.config.environment.deployment.md +27 -4
  42. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  43. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  44. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  45. package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +7 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +16 -0
  47. package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +5 -2
  48. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +19 -0
  49. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  50. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +21 -0
  51. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  52. package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +9 -0
  53. package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
  54. package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
  55. package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
  56. package/dist/knowledge/references/saas.models.flows.run-state.md +9 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  59. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  60. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  61. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  62. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  63. package/dist/knowledge/registries/framework-topics.json +55 -1
  64. package/dist/knowledge/registries/playbooks.json +2 -2
  65. package/dist/knowledge/registries/source-tags.json +1127 -1042
  66. package/dist/knowledge/skills/INDEX.md +2 -2
  67. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +20 -4
  68. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +4 -1
  69. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  70. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  71. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +4 -0
  72. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  73. package/dist/knowledge/skills/config-app-shell/SKILL.md +4 -0
  74. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +3 -0
  75. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  76. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +69 -19
  77. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  78. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +32 -5
  79. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  80. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  81. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  82. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  83. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  84. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  85. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +35 -3
  86. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  87. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +16 -0
  88. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +30 -0
  89. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  90. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +5 -2
  91. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +207 -0
  92. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +9 -0
  93. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  94. package/dist/knowledge/skills/human-decision-notices/SKILL.md +5 -1
  95. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +9 -0
  96. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +7 -0
  97. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +2 -1
  98. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  99. package/dist/knowledge/skills/infra-environment-config/SKILL.md +31 -9
  100. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +27 -4
  101. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  102. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  103. package/dist/knowledge/skills/module-relationships/SKILL.md +27 -1
  104. package/dist/knowledge/skills/provider-backend-package/SKILL.md +32 -4
  105. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  106. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  107. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  108. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  109. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  110. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  111. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  112. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  113. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  114. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  115. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +21 -0
  116. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -0
  117. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +19 -0
  118. package/dist/knowledge/topic-index.json +295 -114
  119. package/dist/tsconfig.build.tsbuildinfo +1 -1
  120. package/package.json +4 -4
@@ -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" |
@@ -103,9 +103,22 @@ UPDATE.
103
103
 
104
104
  ### Step 5 — Specify and label it
105
105
 
106
- Author a role specification (`spec-family-update`) so the purpose grounds the role's labels, and make
107
- sure `roleSpecifications` in `specifications/src/companion-exports.ts` spreads the application's role
108
- specifications beside `engineRoleSpecifications`. Then regenerate labels (`i18n-label-generation`).
106
+ Every custom role gets its own specification, in the same task as the role. The application's
107
+ customer documentation describes each organization role from it, and refuses to publish a role
108
+ that has none.
109
+
110
+ - **File and name:** one file per role, `specifications/src/engine/roles/<role>.role.specification.ts`
111
+ with the role's name in kebab case, exporting `<role>RoleSpecification` in camel case. For
112
+ `FIELD_TECHNICIAN`: `field-technician.role.specification.ts` exporting
113
+ `fieldTechnicianRoleSpecification`, built with `appLevelRoleSpecificationFromDefinition`
114
+ (`spec-family-update`).
115
+ - **Guidance:** write `purpose`, `businessRole`, `authorityBoundary`, `useWhen`, `avoidWhen` and
116
+ `businessConstraints`. The documentation needs every one except `businessRole`, and a role whose
117
+ specification lacks one is not finished.
118
+ - **Wiring:** import it in `specifications/src/companion-exports.ts` and add it to
119
+ `roleSpecifications` there, beside `engineRoleSpecifications`, through `buildRoleSpecificationMap`.
120
+
121
+ Then regenerate labels (`i18n-label-generation`).
109
122
 
110
123
  ### Step 6 — Check who can give it to people
111
124
 
@@ -137,7 +150,7 @@ The complete office/field wiring — role table, organization type, operation ro
137
150
  - [ ] Every custom role is named in at least one operation's `roles`.
138
151
  - [ ] Every operation naming a custom role that tenant administrators must be able to grant also names `ORG_ADMIN` (or a role on its chain), or the role is grantable by the platform super-administrator only.
139
152
  - [ ] No resource stores roles, permissions or role assignments.
140
- - [ ] Each role has a specification and labels.
153
+ - [ ] Each role has `specifications/src/engine/roles/<role>.role.specification.ts` with `purpose`, `authorityBoundary`, `useWhen`, `avoidWhen` and `businessConstraints`, wired into `roleSpecifications`, and labels.
141
154
 
142
155
  ### Grep invariants
143
156
 
@@ -146,6 +159,8 @@ The complete office/field wiring — role table, organization type, operation ro
146
159
  rg -n "role: '" shared-lib/src/engine/roles.ts
147
160
  # each declared role is offered (repeat per role name)
148
161
  rg -n "'FIELD_TECHNICIAN'" wildo.saas.config.ts
162
+ # each declared role has its specification, wired into the companion exports (repeat per role name)
163
+ rg -n "fieldTechnicianRoleSpecification" specifications/src/engine/roles specifications/src/companion-exports.ts
149
164
  # each declared role is named on an operation (repeat per role name)
150
165
  rg -l "'FIELD_TECHNICIAN'" shared-lib/src/modules
151
166
  # grantable by administrators: every role list naming the custom role should also name ORG_MEMBER/ORG_ADMIN (or a role on their chain)
@@ -168,6 +183,7 @@ rg -li "permission|roleassignment|accessrole" shared-lib/src/modules --glob '*.s
168
183
  ## Red Flags
169
184
 
170
185
  - A custom role in `roles.ts` that no operation names (catch with the **named on an operation** grep).
186
+ - A custom role with no `<role>RoleSpecification`, or one the companion exports never add to `roleSpecifications`: the customer documentation refuses to publish (catch with the **specification** grep).
171
187
  - A custom organization role missing from `availableOrgRoles` (catch with the **offered** grep).
172
188
  - A custom role tenant administrators must give, named alone on an operation they cannot call (catch with the **grantable by administrators** grep).
173
189
  - A resource whose schema stores roles, permissions or assignments (catch with the **modelling roles as data** grep — must return empty).
@@ -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/index.ts` |
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
@@ -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>.resource-configurations.ts` |
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
@@ -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
@@ -93,6 +93,13 @@ export const PROVIDER_CAPABILITY_DISCLOSURES: Readonly<Record<BuiltinProviderCap
93
93
  carriedBy: 'each signer\'s name and email address, and the document sent for signature, which the vendor holds signed',
94
94
  linkableToSubjectByApplication: true,
95
95
  },
96
+ // Embedded signing: the signer's name and e-mail again, to open their signing page, and the page the vendor serves in a
97
+ // frame of the application, which reaches the vendor from the signer's browser with the application's origin.
98
+ [BUILTIN_PROVIDER_CAPABILITY.EMBEDDED_ELECTRONIC_SIGNATURE]: {
99
+ categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS],
100
+ carriedBy: 'each signer\'s name and email address, sent again to open their signing page, and the signer\'s browser, which loads that page from the vendor',
101
+ linkableToSubjectByApplication: true,
102
+ },
96
103
  [BUILTIN_PROVIDER_CAPABILITY.BILLING]: {
97
104
  categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS, PersonalDataCategory.FINANCIAL],
98
105
  carriedBy: 'the customer name and email address, and the payment, subscription and invoice records',
@@ -94,6 +94,10 @@ and an `order`), `placedOnThisSurface` (each entry with its `shellIdentity`, its
94
94
  members' section).
95
95
  - A user-menu task lists the placed settings destinations in `USER_DROPDOWN.settingsEntries`; it has no audience.
96
96
  - Nothing declined may remain on any surface.
97
+ - A placed view that was built as a resource operation's custom view (`customView` on one operation in the resource's
98
+ ui-behavior) has no launcher of its own: place a `RESOURCE_OPERATION` entry for that operation. The placement reads it
99
+ as the view when the component's name starts with the view ref's words (`view-enquiry-capture` is carried by an entry
100
+ opening the operation bound to `EnquiryCaptureCustomView`); the shell oracle shows that entry with `hostedCustomView`.
97
101
  - The task lands when `wildo context info app-shell-placement-content` lists every placed identity on the surface,
98
102
  shown to the audience the plan decided, and none of the declined ones. Run it before finishing.
99
103
 
@@ -135,6 +135,7 @@ Access decisions: what an identity was allowed or refused.
135
135
  | `PROVIDER_ACCOUNT_CLAIM_REFUSED` | `provider_account_claim_refused` | Warning | An organization's claim of a vendor account that routes inbound deliveries was REFUSED because another organization's enabled connection already holds it: a connect, or turning a stored connection back on. |
136
136
  | `PROVIDER_CONNECTION_SIGN_IN_AUTHORITY_REFUSED` | `provider_connection_sign_in_authority_refused` | Warning | A connection was REFUSED because the person signing in to the vendor lacked the authority its provider requires of that sign-in (`oauth2.idTokenRequirements`): a Microsoft 365 tenant claim by someone who is not one of the tenant's Global or Teams Administrators, or who is a guest. |
137
137
  | `PROVIDER_DATA_RESIDENCY_REFUSED` | `provider_data_residency_refused` | Warning | A provider call made for an organization was refused before anything was sent, because the organization pins its data to places (`Organization.dataResidency`) the provider cannot be shown to stay inside: its chosen region processes elsewhere, nothing states where it processes, or the call would spend an owner's own connected account nobody placed. |
138
+ | `PROVIDER_GRANT_EXPORTED` | `provider_grant_exported` | Warning | A stored OAuth2 grant LEFT this deployment in its portable form (grant seeding, 2026-11-18): a super-administrator of a development or test deployment exported it so another such deployment can import it. |
138
139
  | `PROVIDER_OPERATION_DENIED` | `provider_operation_denied` | Warning | |
139
140
  | `RELATIONSHIP_CAPABILITY_EXPIRED` | `relationship_capability_expired` | Warning | A lent capability reached its stated end and was relabelled EXPIRED by the credential-expiry sweep: the lending ended on schedule, nobody acting. |
140
141
  | `RELATIONSHIP_CAPABILITY_GRANTED` | `relationship_capability_granted` | Critical | A granting organization lent a representing organization's representatives a named administrative capability, until a stated end. |
@@ -263,6 +264,8 @@ Reads and changes of application data that are recorded for review.
263
264
 
264
265
  | Event | Wire value | Severity | What it records |
265
266
  | --- | --- | --- | --- |
267
+ | `A2A_REMOTE_AGENT_CALL` | `a2a_remote_agent_call` | Information | |
268
+ | `A2A_REMOTE_TASK_PUSH` | `a2a_remote_task_push` | Information | |
266
269
  | `AGENT_BEHAVIOR_REPORT_RECEIVED` | `agent_behavior_report_received` | Warning, raised to Critical by an occurrence that says so | A person reported an agent's reply. |
267
270
  | `AGENT_BEHAVIOR_REPORTED_TURN_READ` | `agent_behavior_reported_turn_read` | Warning | An administrator read the reply a report is about, from the reporter's conversation (`readReportedTurn`): a person's conversation read by someone else, so every read is recorded, with whether the turn was still there. |
268
271
  | `AGENT_CONTENT_QUARANTINED` | `agent_content_quarantined` | Critical | A classifier found a prompt-injection attack in content somebody else wrote, and the agent's model never read it: a tool result reached it as a quarantine notice, or an inbound delivery did not start its turn (`contentSource`). |
@@ -292,6 +292,17 @@ export const BUILTIN_PROVIDER_CAPABILITY = {
292
292
  * levels its contract declares. Maps to `EngineCapability.ELECTRONIC_SIGNATURE`.
293
293
  */
294
294
  ELECTRONIC_SIGNATURE: 'ELECTRONIC_SIGNATURE',
295
+ /**
296
+ * Provider ALSO lets a signer sign inside the application, in a frame showing the vendor's signing page, instead of
297
+ * from the vendor's e-mail (embedded signing). Maps to `EngineCapability.ELECTRONIC_SIGNATURE`, the slot it shares with
298
+ * {@link ELECTRONIC_SIGNATURE}, and is claimed only beside it.
299
+ *
300
+ * A token of its own because vendors split here: DocuSign, Yousign, BoldSign, SignNow and Adobe Acrobat Sign answer a
301
+ * signing page URL the application can frame; IgniSign, Dropbox Sign and Universign need their own browser script, so
302
+ * their providers sign from the e-mail only. The claim is the provider's statement that its contract declares
303
+ * `embeddedSigning`; the engine refuses at startup a claim with no such declaration.
304
+ */
305
+ EMBEDDED_ELECTRONIC_SIGNATURE: 'EMBEDDED_ELECTRONIC_SIGNATURE',
295
306
  /**
296
307
  * Single billing-engagement capability covering everything from
297
308
  * Checkout-style hosted flows to first-party PaymentIntent flows.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: electronic-signature-deliverables
3
- description: Have a deliverable a person approved signed by them with their own electronic signature, through a trust-service vendor, after the approval is sealed. Covers `FunctionTool.electronicSignature` (the level and who signs), the `ELECTRONIC_SIGNATURE` capability and its provider, what makes a signature request SIGNED (the validated signed document, never the vendor's word), the evidence it keeps, and the vendor's notifications. Use when the user says "the client must e-sign the engagement letter", "send the approved report for electronic signature", "we need an advanced electronic signature", "eIDAS signature on the deliverable", "the signature request stays open", or "why is the signed document rejected".
3
+ description: Have a deliverable a person approved signed by them with their own electronic signature, through a trust-service vendor, after the approval is sealed. Covers `FunctionTool.electronicSignature` (the level and who signs), the `ELECTRONIC_SIGNATURE` capability and its provider, what makes a signature request SIGNED (the validated signed document, never the vendor's word), the evidence it keeps, and the vendor's notifications. Use when the user says "the client must e-sign the engagement letter", "send the approved report for electronic signature", "we need an advanced electronic signature", "eIDAS signature on the deliverable", "the signature request stays open", "why is the signed document rejected", or "let the client sign inside the app".
4
4
  user-invocable: false
5
5
  ---
6
6
 
@@ -25,7 +25,8 @@ electronic signature. Some deliverables need more: the approver's OWN advanced e
25
25
  trust-service vendor (an engagement letter, a regulated filing, a contract). This is opt-in per deliverable. You declare
26
26
  it on the agent tool whose call names the file; once a person approves the call and its seal is SEALED, the engine sends
27
27
  exactly the approved bytes to the vendor, tracks the request, and makes it SIGNED only when the signed PDF the vendor
28
- returns validates against the trust anchors its provider pins. Nothing in your code sends, polls or validates.
28
+ returns validates: its signature covers the document and nothing was added after it, and, when the provider pins its
29
+ vendor's certificates (an advanced level needs them), it chains to one. Nothing in your code sends, polls or validates.
29
30
 
30
31
  ## App Paths
31
32
 
@@ -35,6 +36,7 @@ returns validates against the trust anchors its provider pins. Nothing in your c
35
36
  | The capability and its provider | `wildo.saas.config.ts` → `engineCapabilities` (`ELECTRONIC_SIGNATURE`) and its provider selection |
36
37
  | The vendor's notification endpoint | the provider's contract (`notificationEndpointKey`), enabled with the provider's webhooks |
37
38
  | The requests and their evidence | the engine's `signatureRequests` resource (route-less; read through the service tier) |
39
+ | Signing inside the application | `frontend/src/**` → the record's page renders `EmbeddedSigningFrame` |
38
40
 
39
41
  ## When to Use
40
42
 
@@ -58,37 +60,84 @@ returns validates against the trust anchors its provider pins. Nothing in your c
58
60
  `@wildo-ai/saas-backend-lib`. `APPROVER` signs what they approved. Registration refuses a declaration without a
59
61
  deliverable, with no signer, or naming a source twice.
60
62
  3. **Enable `ELECTRONIC_SIGNATURE`** in `wildo.saas.config.ts` and select a provider that applies the level. Startup
61
- refuses a declared level with the capability off, a provider that does not apply it, a provider pinning no trust
62
- anchor for its environment, and a vendor test environment outside development and test.
63
+ refuses a declared level with the capability off, a provider that does not apply it, an advanced level from a
64
+ provider pinning no trust anchor for its environment, and a vendor test environment outside development and test.
63
65
  4. **Enable the vendor's notifications** when its provider names a `notificationEndpointKey`. A notification is never
64
66
  believed: it only causes a re-read. Without it, the poll re-reads open requests every five minutes.
65
67
  5. **Know what happens next** (`references/what-makes-a-request-signed.md`): the poll sends each newly sealed
66
68
  deliverable, re-reads open requests, and moves a request to SIGNED only on a validated signed document, keeping the
67
69
  signed PDF and the validation's evidence. Declined, expired and cancelled requests end; a document that proves another
68
70
  signer or a lower level ends the request FAILED; a document that does not validate leaves it open.
69
- 6. **Verify** with the checks below, then run the migration skill: the request's evidence fields are columns.
71
+ 6. **Let signers sign inside the application** (optional), with a provider claiming `EMBEDDED_ELECTRONIC_SIGNATURE`
72
+ (Yousign, DocuSign): render `EmbeddedSigningFrame` on the record's page and admit the vendor's frame origin in the
73
+ frontend's CSP. See `references/signing-inside-the-application.md`.
74
+ 7. **Verify** with the checks below, then run the migration skill: the request's evidence fields are columns.
70
75
 
71
76
  ## Worked Example
72
77
 
73
- <!-- TIER C WAIVER: no electronic-signature vendor provider exists yet (IgniSign is #2912, the simulator #2911), so no dogfood application can enable ELECTRONIC_SIGNATURE (startup refuses an enabled capability with no provider) and there is no Tier A site to anchor. -->
74
- ```ts
75
- export const sendEngagementLetter: FunctionTool = {
76
- functionRef: 'ledger.sendEngagementLetter',
77
- inputSchema: z.object({ clientId: z.string(), letterFileId: z.string() }),
78
- humanApproval: { route: HumanDecision_RouteKind.OWNER },
78
+
79
+ ## Usage Example
80
+
81
+ ```typescript
82
+ const RequestEngagementLetterSignature_InputSchema = z.object({
83
+ engagementId: z.string().min(1).describe('The engagement. Resolve it with resource.engagements.read.'),
84
+ letterFileId: z.string().min(1).max(200)
85
+ .describe('The id of the engagement\'s letter PDF: `engagementLetter.fileId` as resource.engagements.read returned it. The client signs this file, byte for byte.'),
86
+ });
87
+ type RequestEngagementLetterSignature_Input = z.infer<typeof RequestEngagementLetterSignature_InputSchema>;
88
+
89
+ /** The engagement's fields the client approves beside the letter: shown on the card and committed to by the seal. */
90
+ export const ENGAGEMENT_LETTER_SEALED_FIELDS = ['engagementReference', 'services', 'closeCadence', 'startsOn', 'endsOn'] as const;
91
+
92
+ export const requestEngagementLetterSignatureTool: FunctionTool = {
93
+ functionRef: REQUEST_ENGAGEMENT_LETTER_SIGNATURE_TOOL_REF,
94
+ authority: {
95
+ kind: FunctionToolAuthorityKind.NO_APPLICATION_DATA,
96
+ reason: 'It reads and writes nothing: once the client approves, the engine itself sends the approved letter for signature.',
97
+ },
98
+ effect: FunctionToolEffect.WRITE,
99
+ description:
100
+ 'Ask the client to sign the engagement letter electronically. Pass the engagement id and the id of its letter PDF '
101
+ + '(engagementLetter.fileId from resource.engagements.read); the firm uploads the letter on the engagement first. '
102
+ + 'The client\'s administrator approves the letter, then signs it inside the application, on the engagement\'s page. '
103
+ + 'Call it only when the user asks, then say it is waiting for the client\'s administrator.',
104
+ inputSchema: RequestEngagementLetterSignature_InputSchema,
105
+ personalDataOutput: {
106
+ kind: FunctionToolPersonalDataOutputKind.NOT_FROM_RECORDS,
107
+ reason: 'It returns the two ids it was called with and a fixed sentence; it reads no record.',
108
+ },
109
+ humanApproval: {
110
+ route: HumanDecision_RouteKind.ROLE,
111
+ eligibleRole: CORE_ORG_ROLES.ORG_ADMIN,
112
+ // Signing commits the client to the mandate.
113
+ riskLevel: ResourceOperationRiskLevel.HIGH,
114
+ },
115
+ argumentsResource: { resourceType: ClientEngagements_ResourceType.ENGAGEMENTS, rowIdArgument: 'engagementId' },
79
116
  deliverableFileArgument: 'letterFileId',
80
- electronicSignature: { requiredLevel: ElectronicSignature_Level.ADVANCED, signers: [FunctionTool_SignerSource.APPROVER] },
81
- execute: async (args) => ({ queued: args.letterFileId }),
117
+ sealedRecordFields: ENGAGEMENT_LETTER_SEALED_FIELDS,
118
+ // A letter re-issued and approved again replaces the earlier approval of the same engagement.
119
+ approvalReplacesEarlierApprovalOfRow: true,
120
+ electronicSignature: { requiredLevel: ElectronicSignature_Level.SIMPLE, signers: [FunctionTool_SignerSource.APPROVER] },
121
+ execute: async (args: RequestEngagementLetterSignature_Input) => ({
122
+ engagementId: args.engagementId,
123
+ letterFileId: args.letterFileId,
124
+ // What happens next is the engine's, within minutes and not here: the approved letter is sent for the approver's
125
+ // signature. Said as what WILL happen, never as done.
126
+ next: 'The client\'s administrator approved the letter. The application sends it for their signature within a few minutes; they sign it on the engagement\'s page.',
127
+ }),
82
128
  };
83
129
  ```
84
130
 
85
- The person approves the call with the letter in front of them. Its seal binds the letter's bytes. Within five minutes
86
- the letter goes to the vendor for that person to sign at the advanced level, and the request becomes SIGNED once the
87
- signed PDF validates.
131
+ The firm's assistant names the engagement and its letter. The decision goes to `ORG_ADMIN` in the client organization,
132
+ a role no firm expert holds there, so the person who approves, and therefore signs, is the client. The seal binds the
133
+ letter's bytes and the engagement's terms (`sealedRecordFields`) and is linked to the engagement (`argumentsResource`),
134
+ which is the record whose page shows the signing frame. Within five minutes the letter goes to the vendor for that
135
+ person to sign, and the request becomes SIGNED once the signed PDF validates.
88
136
 
89
137
  ## References
90
138
 
91
139
  - `references/what-makes-a-request-signed.md` — the request's states, what the validation checks, the evidence it keeps, the notifications, and the stated limits.
140
+ - `references/signing-inside-the-application.md` — embedded signing: what the provider declares, the `EmbeddedSigningFrame` component, its route and its answers.
92
141
  - The tool's `electronicSignature`, `deliverableFileArgument` and approval gate are documented in `flows-actors-chat-assistant`'s `references/framework-flows-actors-tool-api.md`.
93
142
 
94
143
  ## Verification
@@ -110,17 +159,18 @@ rg -n "requiredLevel: *'|signers: *\[ *'" backend-api/src
110
159
 
111
160
  | Rationalization | Reality |
112
161
  |---|---|
113
- | "The vendor says it is completed, so mark it signed." | The vendor's status is a claim. Only a signed PDF that validates (byte range, the bytes sent, a chain to the pinned anchors, revocation data, no SHA-1) makes it SIGNED. |
162
+ | "The vendor says it is completed, so mark it signed." | The vendor's status is a claim. Only a signed PDF that validates (byte range, the bytes sent, no SHA-1, and a chain to the pinned anchors with revocation data when the provider pins them) makes it SIGNED. |
114
163
  | "Send the document from my tool's `execute`." | Then nothing binds what is signed to what was approved, and nothing tracks or validates it. Declare `electronicSignature`; the engine sends the sealed bytes. |
115
- | "Use the vendor's sandbox in production while we wait for the contract." | A sandbox chain never reaches the production anchors, so every request would stay open. Startup refuses it outside development and test. |
164
+ | "Use the vendor's sandbox in production while we wait for the contract." | Startup refuses a vendor test environment outside development and test. There, a sandbox document is accepted unvalidated so the flow can be run end to end, and its evidence says so (`accepted_from_test_environment`); in production only a validated document makes a request SIGNED. |
116
165
  | "Let the model choose who signs." | Signers come from a closed vocabulary (`FunctionTool_SignerSource`), never from what the model wrote. |
166
+ | "The signer came back from the signing frame, so mark it signed." | Coming back says they left the vendor's page. Only the validated signed document, at the next re-read, makes it SIGNED. |
117
167
  | "Rewrite the PDF to add a cover page after signing." | Anything appended after the last signature but validation data is refused: what was signed would no longer be the document. |
118
168
 
119
169
  ## Red Flags
120
170
 
121
171
  - A tool declaring `electronicSignature` with no `deliverableFileArgument` — startup refuses it; catch it with the declarations command.
122
172
  - A string literal level or signer — catch with the literal command.
123
- - Requests staying open with "no trust anchor" or "does not chain" — the provider's contract pins the wrong environment's anchors; the capability check catches a missing provider.
173
+ - Requests staying open with "does not chain" — the provider's contract pins the wrong environment's anchors; the capability check catches a missing provider.
124
174
  - A deliverable sent from tool code by hand — catch it by reviewing every file the declarations command lists.
125
175
 
126
176
  ## Related Skills
@@ -0,0 +1,113 @@
1
+ # Signing inside the application (embedded signing)
2
+
3
+ By default the vendor e-mails each signer a link to its signing page. With embedded signing, a signer who is signed in to
4
+ your application signs in a frame of it instead, on the page where they meet the record.
5
+
6
+ ## Which vendors can
7
+
8
+ Embedded signing is its own provider capability, `EMBEDDED_ELECTRONIC_SIGNATURE`, claimed beside
9
+ `ELECTRONIC_SIGNATURE` by a provider whose vendor answers a signing page URL the application can frame:
10
+
11
+ | Vendor | Embedded | Registry provider |
12
+ |---|---|---|
13
+ | Yousign | yes | `providers/yousign` |
14
+ | DocuSign | yes (the application's own account, JWT grant) | `providers/docusign-esignature` |
15
+ | BoldSign, SignNow, Adobe Acrobat Sign | the vendor can | none yet |
16
+ | IgniSign, Dropbox Sign, Universign | no: their embedded mode needs their own browser script | IgniSign: `providers/ignisign`, e-mail only |
17
+
18
+ ## What it takes
19
+
20
+ 1. **A provider that claims it.** Its contract carries an `embeddedSigning` block (the vendor's frame origins, and two
21
+ functions: build the vendor call that asks for one signer's signing page, and read its URL from the answer, or `null`
22
+ while it is not that signer's turn) and lists `openSigningSession` in its `operations`. A claim without the block
23
+ refuses startup; a block without the claim is never offered. Whether its signers sign in the application or from the
24
+ vendor's e-mail is the provider's own configuration, a constant at the top of its `exchange.ts`.
25
+ 2. **The vendor's frame origins in the CSP, which you do not write.** `wildo config sync` records the origins the
26
+ provider declares, and `wildo dev sync-csp` adds them to the SaaS frontend's `frame-src`: run both after installing or
27
+ selecting the provider. The engine refuses a signing page on any other origin. Some vendors also require your
28
+ application's domain to be allowed in their own dashboard (Yousign) before their page may be framed.
29
+ 3. **Room at the bottom of the last page.** Each signer's signature field goes there, two per row: vendors that need a
30
+ placed field (DocuSign, Yousign) get the last page the engine measured.
31
+ 4. **The frame on the record's page**, from `@wildo-ai/saas-frontend-lib`:
32
+
33
+ ## Import Origins
34
+
35
+ - `@wildo-ai/saas-frontend-lib`
36
+
37
+ ## Source Excerpts
38
+
39
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
40
+
41
+ ```tsx
42
+ /**
43
+ * Embedded signing: the signed-in person signs a record's deliverable at the signature vendor, inside a frame of the
44
+ * application, instead of following the vendor's e-mail. Import from `@wildo-ai/saas-frontend-lib`.
45
+ *
46
+ * Place it where the person meets the record (an engagement letter's page, say). On mount it asks the backend for the
47
+ * vendor's signing page (`signatureRequestSigners.openSigningSession`). The answer is given only to a signer an open
48
+ * request on that record names and the vendor says has not signed yet, so for anybody else, once the person has signed,
49
+ * and when the request's provider signs from its e-mail only, the component renders NOTHING. The page is valid for
50
+ * minutes and is never stored, which is why it is asked for here, when the person is in front of it. A signer whose turn
51
+ * has not come (signers who sign in turn) is shown nothing either, until it does.
52
+ *
53
+ * When the person is done, a vendor that redirects sends the frame to the application's own {@link SIGNING_RETURN_PAGE_PATH};
54
+ * the frame sees it arrive (it is now same-origin), closes, and calls `onSigningReturned`. A vendor that does not redirect
55
+ * (or redirects to another of the application's origins) keeps showing its own end page. Either way nothing here says the
56
+ * document is signed: every vendor's own guidance is that the end of the frame is not the outcome, and the request becomes
57
+ * SIGNED only once the engine has validated the signed document, at its next re-read (poll or vendor notification).
58
+ *
59
+ * What it needs elsewhere: a provider that claims `EMBEDDED_ELECTRONIC_SIGNATURE` and declares `embeddedSigning`, and a
60
+ * `wildo config sync` then `wildo dev sync-csp` since it was added, which put the vendor's signing origins in the SaaS
61
+ * frontend's CSP `frame-src` from the provider's own declaration; without them the browser refuses to load the frame.
62
+ *
63
+ * It renders no words of its own: the application passes the frame's accessible `title`.
64
+ */
65
+ export interface EmbeddedSigningFrameProps {
66
+ /** The record the deliverable belongs to: the signature request's `linkedResourceType`. */
67
+ readonly linkedResourceType: string;
68
+ /** The record the deliverable belongs to: the signature request's `linkedResourceId`. */
69
+ readonly linkedResourceId: string;
70
+ /** The frame's accessible name (WCAG 4.1.2), in the person's language, e.g. "Sign the engagement letter". */
71
+ readonly title: string;
72
+ /** Called once the person left the vendor's page. Re-read the record if you show its signature state. */
73
+ readonly onSigningReturned?: () => void;
74
+ readonly className?: string;
75
+ }
76
+ ```
77
+
78
+ Give it the record the deliverable belongs to (the same `linkedResourceType` / `linkedResourceId` the request carries) and
79
+ the frame's accessible title, from your labels.
80
+
81
+ ## What happens
82
+
83
+ - On mount the frame asks `POST /api/v1/applications/{applicationId}/signature-request-signers/open-signing-session`.
84
+ Any signed-in user may ask; a page is answered only to a signer an open request on that record names, keyed on the
85
+ caller's own user id, on their own request: a machine credential or a one-off token is refused, and a client the person
86
+ delegated to (A2A, MCP) cannot reach the route at all. Before opening a page the engine asks the vendor whether this
87
+ signer has already signed. For
88
+ anyone else, once the person has signed, and when the request's provider signs from its e-mail only, the frame renders
89
+ nothing.
90
+ - Each opening is a HIGH-risk operation, so the audit trail records who opened a signing page and when.
91
+ - The page URL is valid for minutes and is never stored, which is why it is asked for when the person is in front of it.
92
+ - When the person is done, a vendor that redirects sends the frame to the application's own signing-return page
93
+ (`SIGNING_RETURN_PAGE_PATH`; the engine hands it to the vendor when sending and when opening the session), the frame
94
+ closes and calls `onSigningReturned`. A vendor that does not redirect keeps showing its own end page. Neither says the
95
+ document is signed: the request becomes SIGNED only once the engine has validated the signed document, at its next
96
+ re-read (in a vendor's test environment in development or test, once it has accepted it unvalidated, marked so).
97
+
98
+ | Answer | Meaning |
99
+ |---|---|
100
+ | 201 | The signing page: its `url` and, when the vendor says, `expiresAt` |
101
+ | 400 | The return URL is not on one of the application's own frontends |
102
+ | 403 | Not a person on their own request (a machine credential, a one-off token) |
103
+ | 404 | Nothing on that record left for this person to sign |
104
+ | 409 | The request's provider signs from its e-mail only (the frame renders nothing) |
105
+ | 502 | The vendor answered no page; asking again may succeed |
106
+
107
+ ## Limits
108
+
109
+ - Only the signer can be shown their page. An administrator cannot open it on their behalf.
110
+ - A signer whose turn has not come (signers who sign in turn) is shown nothing until it does.
111
+ - The return page renders nothing: the application's root does not boot on it, so no session is restored inside the frame.
112
+ - With a provider whose vendor sends no e-mail to an embedded signer, the person learns of the document only where your
113
+ application shows the frame. Put it where they will see it, or tell them yourself.
@@ -6,7 +6,7 @@
6
6
  |---|---|---|
7
7
  | SENT | Sent; nobody has signed yet, as far as the vendor reports. | no |
8
8
  | PARTIALLY_SIGNED | The vendor reports that some signers signed. A claim, never evidence. | no |
9
- | SIGNED | The signed document validated and proves every signer at the required level. | yes |
9
+ | SIGNED | The signed document validated and proves every signer at the required level (`validatedAt` set); or, in a vendor's test environment in development or test only, it was accepted unvalidated (no `validatedAt`, see below). | yes |
10
10
  | DECLINED | A signer refused. | yes |
11
11
  | EXPIRED | The vendor's deadline passed. | yes |
12
12
  | CANCELLED | Withdrawn before it was signed, at the vendor or because its record went. | yes |
@@ -25,10 +25,12 @@ A vendor's "completed" moves nothing by itself. The engine downloads the signed
25
25
  `/Annots` and a document security store (`/DSS`) may be added. After the last signature, only a `/DSS` update.
26
26
  Every appended cross-reference section must be one the check read, chained to the one before it, so a section hidden
27
27
  inside a stream's data cannot be the one a PDF reader follows.
28
- - **The chain.** The signer's certificate chains, at the claimed signing time (which must fall within the request's
29
- life), to an anchor the provider pins for its vendor environment.
30
- - **Revocation.** Every certificate below the anchor has a CRL or OCSP response saying it is not revoked: the one the
31
- signature carries, or a CRL fetched now from the certificate's distribution point.
28
+ - **The signing time.** The time the signature claims falls within the request's life.
29
+ - **The chain, when the provider pins certificates.** The signer's certificate chains, at that time, to an anchor the
30
+ provider pins for its vendor environment. Pinning is optional: a provider that pins none is validated without its
31
+ chain, proves the simple level only, and its evidence records `chainCheck: not_checked`. An advanced level needs it.
32
+ - **Revocation, with the chain.** Every certificate below the anchor has a CRL or OCSP response saying it is not
33
+ revoked: the one the signature carries, or a CRL fetched now from the certificate's distribution point.
32
34
  - **Algorithms.** SHA-256, SHA-384 or SHA-512 throughout; SHA-1 and RSA keys under 2048 bits are refused.
33
35
  - **Signer and level.** At ADVANCED, every signer's certificate names their e-mail address and carries a certificate
34
36
  policy the provider declares as advanced.
@@ -36,6 +38,27 @@ A vendor's "completed" moves nothing by itself. The engine downloads the signed
36
38
  A document that fails any check leaves the request open (the poll reads it again). One that validates but proves another
37
39
  signer or a lower level ends it FAILED.
38
40
 
41
+ ## A vendor's test environment
42
+
43
+ A vendor's sandbox (Yousign's, DocuSign's demo) applies no legal signature: its document carries a visual signature only,
44
+ so it never validates. In a development or test runtime, when the vendor reports the request complete and the validator
45
+ refuses its document, the engine still records the request SIGNED, so the whole flow can be run before production:
46
+
47
+ - it moves through its own event, `evidence_accepted_from_test_environment`, and carries no `validatedAt`: a SIGNED
48
+ request with `validatedAt` validated, one without it did not, and nothing names it as a validated copy;
49
+ - the evidence file says `standing: accepted_from_test_environment` and keeps the validator's refusal as
50
+ `testEnvironmentRefusal`; it proves no signer;
51
+ - the `SIGNATURE_REQUEST_MOVED` event says `evidenceStanding: accepted_from_test_environment`;
52
+ - the vendor returning exactly the bytes that were sent is never accepted: that is a provider downloading the original,
53
+ which would leave every production request open, and the sandbox run is where it must show;
54
+ - a document that proves ANOTHER signer or a lower level is still refused (FAILED);
55
+ - both conditions are required: a NON_PRODUCTION vendor environment AND a development or test runtime. Startup already
56
+ refuses a vendor test environment anywhere else, and an undeclared runtime environment is production.
57
+
58
+ In production nothing changes: a document that does not validate keeps the request open, and the backend logs why, once
59
+ per request and kind of refusal (`its evidence is refused`), with the validator's own words, so a vendor whose real documents
60
+ the validator refuses is diagnosed rather than guessed at.
61
+
39
62
  ## The evidence it keeps
40
63
 
41
64
  A SIGNED request names two files of its own, written in the same move: the signed PDF (a vendor-signed copy of the
@@ -67,6 +90,10 @@ poll re-reads that request within five minutes.
67
90
  ## Stated limits
68
91
 
69
92
  - One document per request. A request the vendor split into several documents is left open.
93
+ - The vendor environment is read when the request is re-read (from the provider's base URL then), not recorded when it
94
+ was sent. Switching a provider's base URL between sandbox and production while requests are open makes them read in
95
+ the new environment: anchors chosen, and a test-environment acceptance decided, by the URL in force. Development only,
96
+ since production refuses a sandbox URL at startup.
70
97
  - A signer's e-mail address is compared as it is now. One changed since the invitation does not match the certificate;
71
98
  a signer with no address on record leaves the request open.
72
99
  - An OCSP response the signature carries counts only once it verifies (signed by the certificate's issuer or a responder
@@ -207,10 +207,10 @@ co-location conventions.
207
207
 
208
208
  ### Step 4: Contribute the definition through its owning module
209
209
 
210
- Inspect the existing backend module's `emailTemplateDefinitions` slot before choosing a layout. The current skeleton scans compiled email directories; an older application may maintain an explicit map. Preserve the actual ownership and registration path rather than adding a parallel map with a prescribed filename.
210
+ Inspect the owning backend module's `emailTemplateDefinitions` slot first. A business module's emails live in `backend-api/src/modules/<module>/emails/`, registered by `emails/module-email-template-definitions.ts` scanning `resources/` (and `system/`); never create `email/` or another folder for them, and never add a second definitions file. The build lane's `check:module-layout` refuses a module's email definitions outside `emails/` and states the move (`mv`) that corrects it. If the module registers them elsewhere, move them to `emails/` (folder and imports) before adding the template.
211
211
 
212
212
  - The scanner loads `template.js` default exports and co-located `labels.<locale>.js` named `labels` exports. Author their TypeScript sources and let the normal compiler publish them; a new `.tsx` file alone is not a loaded runtime template.
213
- - The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>`, and under `resources/` turns the path into the ref by replacing `/` with `.`. Module-specific scanners may choose other mappings. Match the existing sender's typed ref to that mapping; creating an enum with a different value does not rename the scanned ref.
213
+ - The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>`, and under `resources/` turns the path into the ref by replacing `/` with `.`. A business module's scanner keeps that standard mapping (`subdir` written as a string, `keyFromPath` returning `` `email.${…}` `` with `/` turned into `.`): the companion reads the folder and the prefix from the call to place generated templates, and assumes the rest of the mapping. Match the sender's typed ref to it; creating an enum with a different value does not rename the scanned ref.
214
214
  - **An operation's email (a `userNotifications` EMAIL entry) has a derived ref:** `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, so its directory is `resources/<resource>/<operation>[.<variantKey>].<target>[_<customNotificationRef>]/` — for example `resources/todos/change_status.admin.users-custom_notify-creator/`. The target segment is always there, and an operation with a keyed variant needs one template per variant. A missing one only WARNS at startup (it refuses only for a token-bearing operation), and the email is silently never sent. Read `references/framework-operation-email-template-ref-api.md` before naming the directory.
215
215
  - **Declare before you code.** A non-user recipient at an address on the record is `recipientEmailField`; another organization named on the record (the other party of something two organizations share) is `recipientOrganizationIdField` on an organization target; an email owed whatever the preferences is `alwaysDeliver: true`. Send from custom code with `EmailBackendService.send` only for an attachment, several or nested addresses, cc / bcc / threading, or a non-user's own language. Read `references/framework-email-send-api.md`.
216
216
  - Contribute the resulting map through the existing owning backend module. For an explicit map, add the imported definition and locale labels there; for a scanner, put the correctly exported files under the scanned directory. Do not manually edit generated definitions or add duplicate registrations.
@@ -391,6 +391,7 @@ single self-contained reference shape for app developers.
391
391
  - [ ] Labels exist for **every** user-visible string (one key per string), satisfying the typed `TLabels` interface key-for-key
392
392
  - [ ] Labels files exist for every supported locale (parallel key sets across locales)
393
393
  - [ ] Compiled template and labels resolve under the owning module’s scanner/map, and its ref matches the sender’s typed id
394
+ - [ ] A business module's email definitions file and templates are under `backend-api/src/modules/<module>/emails/` (the build lane's `check:module-layout` refuses any other folder; `rg -l 'scanEmailTemplateDirectory' backend-api/src/modules` lists only `emails/` files)
394
395
  - [ ] An operation email's directory carries the full derived ref (`<operation>[.<variantKey>].<target>[_<customNotificationRef>]`), one per keyed variant, and startup logs no unresolved operation email
395
396
  - [ ] Definition explicitly selects `EmailTemplateType.*` and the corresponding provider capability is configured
396
397
  - [ ] Definition is typed `EmailTemplateDefinition<TLabels>` (not `any`, not bare `EmailTemplateDefinition`)