@wildo-ai/framework-knowledge 1.1.14 → 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.
Files changed (94) 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/esm/framework-knowledge.definitions.d.ts +1 -1
  4. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  5. package/dist/esm/framework-knowledge.definitions.js +9 -0
  6. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  7. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  8. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  10. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  11. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  12. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  13. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  14. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  15. package/dist/knowledge/manifest.json +7 -7
  16. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  17. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  18. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  19. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  20. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  21. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  22. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  23. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  24. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +4 -0
  25. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  26. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  27. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
  28. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
  29. package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
  30. package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
  31. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  32. package/dist/knowledge/references/integration-plan.config.md +78 -8
  33. package/dist/knowledge/references/platform.config.environment.deployment.md +27 -4
  34. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  35. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  36. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  37. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
  38. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  39. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  40. package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
  41. package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
  42. package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
  43. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  44. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  45. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  46. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  47. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  48. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  49. package/dist/knowledge/registries/framework-topics.json +45 -1
  50. package/dist/knowledge/registries/playbooks.json +2 -2
  51. package/dist/knowledge/registries/source-tags.json +1080 -1012
  52. package/dist/knowledge/skills/INDEX.md +2 -2
  53. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +4 -1
  54. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  55. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  56. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +4 -0
  57. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  58. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
  59. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  60. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
  61. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  62. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  63. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  64. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  65. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  66. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  67. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  68. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
  69. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  70. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
  71. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
  72. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  73. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
  74. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  75. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  76. package/dist/knowledge/skills/infra-environment-config/SKILL.md +31 -9
  77. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +27 -4
  78. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  79. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  80. package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
  81. package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
  82. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  83. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  84. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  85. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  86. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  87. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  88. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  89. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  90. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  91. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  92. package/dist/knowledge/topic-index.json +231 -84
  93. package/dist/tsconfig.build.tsbuildinfo +1 -1
  94. package/package.json +4 -4
@@ -13,3 +13,20 @@ Declare the module's intended `services` in `wildo.saas.config.ts` as well. This
13
13
  supplies bootstrap topology; it does not insert identifiers into source registries.
14
14
  Use `module-registration` for the canonical loader details. Omit layers that the chosen topology
15
15
  does not need, and do not copy empty directories or invent a per-module label owner.
16
+
17
+ ## Conventional folders inside a module (checked)
18
+
19
+ Some module files are read ONLY at one place, so a file elsewhere compiles and is then silently not read. The build
20
+ lane's `check:module-layout` refuses each of these outside its folder, and its finding is the correction: the move (`mv`)
21
+ and every relative import to update. Put them there from the start; when you meet one elsewhere, move it.
22
+
23
+ | Package | File | Its only place (under `src/modules/<module>/`) | What reads it there |
24
+ |---|---|---|---|
25
+ | `backend-api` | The email definitions file (calls `scanEmailTemplateDirectory`) and its templates | `emails/` (never `email/`, `mail/` or the module root) | The companion's email generation and preview |
26
+ | `backend-api` | Custom operations, `*.operation.ts` | under `resources/` (`resources/<resource>/…`) | `resources/index.ts`, which scans only that folder |
27
+ | `shared-lib` | `<resource>.schemas.ts`, `<resource>.resources-config.ts` | `resources/<resource>/` | The build lane's landed checks |
28
+ | `shared-lib` | `<module>.relationships.ts` | `resources/` | The build lane's landed checks |
29
+ | `frontend` | `<resource>.ui-behavior.tsx` | `resources/<resource>/` | The build lane's landed checks |
30
+ | `specifications` | `<resource>.resource.specification.ts` | `resources/` | The build lane's landed checks |
31
+
32
+ Do not create a second folder of the same kind beside the conventional one (`email/` beside `emails/`).
@@ -35,7 +35,7 @@ declaration a chat could not run.
35
35
 
36
36
  | Surface | Typical path |
37
37
  |---|---|
38
- | The operation's declaration | `shared-lib/src/modules/<module>/<resource>/<resource>.resources-config.ts` |
38
+ | The operation's declaration | `shared-lib/src/modules/<module>/resources/<resource>/<resource>.resources-config.ts` |
39
39
  | The words a command shows (title, field labels, enum values) | your label tree, generated by `wildo generate labels` |
40
40
  | The inbound handler that runs commands | `backend-api/src/**/` (the provider skill's section 8) |
41
41
  | The vendor registration | `wildo providers register <ref>` (Slack manifest, Teams package) |
@@ -286,6 +286,34 @@ export const HttpApiFieldMappingSchema = z.strictObject({
286
286
  create: z.string().min(1).optional(),
287
287
  update: z.string().min(1).optional(),
288
288
  }).optional(),
289
+ /**
290
+ * #3953 — WRITE this field through a LOOKUP (Odoo only): a create or update sends `remoteField` of this object instead
291
+ * of the mapping's own `remoteField`, set to the id of the ONE `lookupEntityRef` record whose `lookupRemoteField`
292
+ * equals the value the resource holds. Reads keep the mapping's own `remoteField`.
293
+ *
294
+ * For a field the system of record shows as a code but stores as a reference to another record. On Odoo a partner's
295
+ * `country_code` is the RELATED `country_id.code`: it reads the ISO code, and a write to it is accepted and discarded
296
+ * (measured on Odoo 19.0). The country is written through `country_id`, a many2one to `res.country`:
297
+ *
298
+ * ```ts
299
+ * { localField: 'country', remoteField: 'country_code',
300
+ * writeThrough: { remoteField: 'country_id', lookupEntityRef: 'res.country', lookupRemoteField: 'code' } }
301
+ * ```
302
+ *
303
+ * Each write with a value looks it up once more (one `search_read` on the lookup model, before anything is sent). The
304
+ * match is EXACT and case-sensitive (`'fr'` names no country whose code is `'FR'`), and Odoo leaves archived records
305
+ * of the lookup model out by default. A value no record matches is refused as the caller's
306
+ * (`SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED`); a value several records match, or a `remoteField` that Odoo does not
307
+ * describe as a many2one to `lookupEntityRef`, is refused as the binding's (`SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID`).
308
+ * Nothing is sent either way. An empty value (`null` or `''`) unsets the reference (Odoo's `false`). Refused at
309
+ * registration on any other dialect, on a binding that opens neither create nor update, and when the field it writes is
310
+ * another mapping's field or another write-through's.
311
+ */
312
+ writeThrough: z.strictObject({
313
+ remoteField: z.string().min(1),
314
+ lookupEntityRef: z.string().min(1),
315
+ lookupRemoteField: z.string().min(1),
316
+ }).optional(),
289
317
  });
290
318
  ```
291
319
 
@@ -985,6 +1013,29 @@ export function assertHttpApiBindingDialectCoherence(binding: HttpApiResourceBin
985
1013
  }
986
1014
  }
987
1015
 
1016
+ // #3953 — a write through a lookup is Odoo's (a code shown, a reference stored), and only a write uses it.
1017
+ for (const mapping of binding.fieldMappings) {
1018
+ if (mapping.writeThrough === undefined) continue;
1019
+ const at = `fieldMappings('${mapping.localField}').writeThrough`;
1020
+ if (binding.dialect !== HttpApiTransportDialect.ODOO_JSONRPC && binding.dialect !== HttpApiTransportDialect.ODOO_JSON2) {
1021
+ throw new Error(`${at}: declared on a ${binding.dialect} binding. It resolves a value through a lookup on another Odoo model before a write, and only the Odoo dialects compile one.`);
1022
+ }
1023
+ if (!binding.writableVerbs.includes(HttpApiWriteVerb.CREATE) && !binding.writableVerbs.includes(HttpApiWriteVerb.UPDATE)) {
1024
+ throw new Error(`${at}: this binding opens neither create nor update, so nothing would ever be written through it. Remove it, or open the verb.`);
1025
+ }
1026
+ // Two values for one remote field in one write: whichever is written last would win, silently.
1027
+ const target = mapping.writeThrough.remoteField;
1028
+ const clash = binding.fieldMappings.find((other) => other !== mapping
1029
+ && (other.remoteField === target || other.writeThrough?.remoteField === target));
1030
+ if (clash !== undefined) {
1031
+ throw new Error(`${at}: writes '${target}', which fieldMappings('${clash.localField}') also writes. One remote field takes one value per write.`);
1032
+ }
1033
+ // The population's create values are the engine's (#2552): a create writes them, and the lookup would replace one.
1034
+ if (Object.prototype.hasOwnProperty.call(binding.populationFilter?.createValues ?? {}, target)) {
1035
+ throw new Error(`${at}: writes '${target}', which the population filter's createValues also writes on every create. One remote field takes one value per write.`);
1036
+ }
1037
+ }
1038
+
988
1039
  // #2552 — the population filter: expressible by this dialect's list, and satisfied by what a create writes.
989
1040
  assertHttpApiPopulationFilterCoherence(binding as never);
990
1041
 
@@ -149,13 +149,22 @@ once per pass, however many rows share a second and however a page boundary fall
149
149
  An incremental pass never re-reads a row that did not change in the source. So a change on YOUR side
150
150
  would otherwise reach only rows that happen to change remotely afterwards. The pipeline fingerprints
151
151
  everything that decides what is extracted and how a row is loaded — binding, key fields, the whole
152
- mapping, `sourceFilter`, `archivedRecords`, the partition fields, the operator's partition
153
- ASSIGNMENTS, and the owner organization. When the fingerprint changes, the watermark is dropped and
154
- the next incremental pass reads the whole source once. The run reports
152
+ mapping, `sourceFilter`, the binding's `populationFilter`, `archivedRecords`, the partition fields,
153
+ the operator's partition ASSIGNMENTS, and the owner organization. When the fingerprint changes, the
154
+ watermark is dropped and the next incremental pass reads the whole source once. The run reports
155
155
  `incrementalTrackReset: extraction-basis-changed` (or `no-track` on the first ever pass).
156
156
 
157
- Schedule, `maxRowsPerRun`, `lookbackSeconds`, the orphan policy and the population are NOT in the
158
- fingerprint: they change how often or how carefully rows are read, not what a row holds.
157
+ **The run also names WHAT changed**, in `changedBasisParts` on the run report and on the pipeline
158
+ state's `lastRunSummary`, and in the reset's log line: `source`, `keys`, `mapping`, `source-filter`,
159
+ `population-filter`, `archived-records`, `partition-fields`, `partition-assignments`, `owner`,
160
+ `reference-targets`. Read it before suspecting the pipeline. The common cause of a reset nobody
161
+ expected is `partition-assignments`: an operator assigned, unassigned or moved a partition between
162
+ two runs, and the reset is what makes the newly assigned rows load. The run-history row
163
+ (`wildo context pipelines --runs`) carries only the reason; the parts are on the summary of the last run.
164
+
165
+ Schedule, `maxRowsPerRun`, `lookbackSeconds`, the orphan policy and the destination's `population`
166
+ (`CLOSED` / `OPEN`) are NOT in the fingerprint: they change how often or how carefully rows are read,
167
+ not what a row holds.
159
168
 
160
169
  The FULL pass keys on the same fingerprint. A full pass that spans several runs records the
161
170
  fingerprint it started under, and a run under a different one ABANDONS it and starts a new full pass
@@ -570,6 +570,36 @@ export enum SystemOfRecordErrorCode {
570
570
  */
571
571
  WRITE_FIELD_NOT_WRITABLE = 'SYSTEM_OF_RECORD_WRITE_FIELD_NOT_WRITABLE',
572
572
 
573
+ /**
574
+ * REQUEST — a create or update refused, with a CONFIGURATION error type, because the binding maps a field onto a
575
+ * remote field the system of record COMPUTES and does not store, so a
576
+ * write to it would be accepted and discarded (#3953). Odoo answers `true` to a `create` or `write` naming such a field
577
+ * and keeps nothing: measured on Odoo 19.0, `res.partner.country_code` (related to `country_id.code`) written alone
578
+ * read back `false`. Refused before anything is sent, because the alternative is a write reported as done that changed
579
+ * nothing. The context names the field and, when the system of record says so, the field it is computed from
580
+ * (`computedFrom`), which is the one to write.
581
+ *
582
+ * Not the caller's to fix: the binding's mapping is wrong for writes, so it is a configuration error.
583
+ */
584
+ WRITE_FIELD_COMPUTED_REMOTELY = 'SYSTEM_OF_RECORD_WRITE_FIELD_COMPUTED_REMOTELY',
585
+
586
+ /**
587
+ * REQUEST — a field written through a lookup (`fieldMappings[].writeThrough`, #3953) holds a value no record of the
588
+ * lookup model matches (an ISO country code Odoo does not know, or `'fr'` where the records hold `'FR'`: the match is
589
+ * exact). Refused before anything is sent: writing nothing would report the field as written, and writing a guess
590
+ * would put the row in the wrong place. The context names the field, the lookup model and the value.
591
+ */
592
+ WRITE_VALUE_UNRESOLVED = 'SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED',
593
+
594
+ /**
595
+ * REQUEST — a create or update refused, with a CONFIGURATION error type, because a field's write-through lookup
596
+ * (`fieldMappings[].writeThrough`, #3953) cannot name ONE record: the
597
+ * value matches several records of the lookup model (the lookup field does not identify a record), a match carries no
598
+ * integer id, or the field written is not a many2one to the lookup model as the system of record describes it. The
599
+ * binding's fault, not the caller's; nothing is sent. The context names the field, the lookup model and why.
600
+ */
601
+ WRITE_LOOKUP_INVALID = 'SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID',
602
+
573
603
  /**
574
604
  * REQUEST — the write was SENT and nobody knows whether the system of record applied it: the call
575
605
  * timed out, the connection dropped after the request left, or a gateway answered for the vendor.
@@ -88,3 +88,8 @@ Work down this list; the first two are almost always the answer.
88
88
  5. **A document declaring a shared-secret `token_endpoint_auth_method` is refused.** These clients
89
89
  are public and authenticate with PKCE; a secret would have to be arranged out of band, which
90
90
  defeats the point of the mechanism.
91
+ 6. **A client that is not on your machine cannot reach `http://localhost`**, and some (Claude Desktop)
92
+ refuse a plain-`http` URL outright. `wildo local tunnel up` gives the application a public HTTPS origin
93
+ for the length of a test: the MCP endpoint, the OAuth endpoints and the discovery documents are
94
+ forwarded, nothing else is. Tokens minted before `up` stop working after it. A client that must show
95
+ your consent page in a browser needs the frontend exposed too, which the tunnel does not do yet.
@@ -400,7 +400,9 @@ rather than an instruction to interpret every empty list as an empty knowledge b
400
400
  * return the passage. A passage found only by the lexical arm carries no `vectorRank`, and every
401
401
  * passage in a lexical-only call carries none — which is the expected state when the application
402
402
  * configures no embeddings provider, or when text was committed more recently than the background
403
- * worker has embedded it.
403
+ * worker has embedded it. Such a not-yet-embedded passage is not ranked BELOW embedded ones for that
404
+ * reason alone: when the vector arm ran and could not rank it, its `fusion` counts its lexical rank for
405
+ * both arms, so text written a minute ago competes on its wording from the moment it is committed.
404
406
  *
405
407
  * @example
406
408
  * // Show the strongest passages, and say WHY each was found.
@@ -417,7 +419,7 @@ rather than an instruction to interpret every empty list as an empty knowledge b
417
419
  export interface RagChunkRetrievalScores {
418
420
  /** Reciprocal-rank-fusion score. Ordering key. Not a probability and not comparable across queries. */
419
421
  fusion: number;
420
- /** 1-based rank within the vector arm, absent when that arm did not return this chunk. */
422
+ /** 1-based rank within the vector arm, absent when that arm did not return this chunk (never imputed). */
421
423
  vectorRank?: number;
422
424
  /** Cosine similarity in `[-1, 1]` (`1 - cosine_distance`). Absent with the rank. */
423
425
  vectorSimilarity?: number;