@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
package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md
CHANGED
|
@@ -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,
|
|
153
|
-
ASSIGNMENTS, and the owner organization. When the fingerprint changes, the
|
|
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
|
-
|
|
158
|
-
|
|
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.
|
package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md
CHANGED
|
@@ -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;
|
|
@@ -120,8 +120,9 @@ What the person sees when a transition is unavailable:
|
|
|
120
120
|
operation's `unavailableWhen` in its specification (`spec-resource-update`). Write that sentence for
|
|
121
121
|
every transition. Give the view `actionVisibility: WHEN_AVAILABLE` in the ui-behavior to hide it
|
|
122
122
|
there too;
|
|
123
|
-
- a call made anyway (an old tab, an API client) is refused by the engine before any hook, as
|
|
124
|
-
`service_resource_operation_disabled
|
|
123
|
+
- a call made anyway (an old tab, an API client) is refused by the engine before any hook, as 409
|
|
124
|
+
`service_resource_operation_disabled` (403 when the condition also read the caller on its way to
|
|
125
|
+
`false`: put the status check first), and the toast speaks the same `unavailableWhen` sentence.
|
|
125
126
|
A refusal the handler raises for any other reason carries a declared code (`backend-custom-operation`).
|
|
126
127
|
|
|
127
128
|
## Worked Example
|
|
@@ -26,10 +26,17 @@ not say is offered and then refused.
|
|
|
26
26
|
*
|
|
27
27
|
* The engine calls `enabledCondition` in TWO places with these parameters, so one function decides both: in the frontend
|
|
28
28
|
* before it offers the action (a list judges each SUMMARY row, a record page the full row), and in the backend before the
|
|
29
|
-
* operation runs, where a `false` refuses the call with
|
|
29
|
+
* operation runs, where a `false` refuses the call with `service_resource_operation_disabled` before any hook. So a
|
|
30
30
|
* condition must say EVERYTHING the operation's handler would refuse on the row's state or on who is asking, or the
|
|
31
31
|
* action is offered and then refused.
|
|
32
32
|
*
|
|
33
|
+
* The refusal's status follows what the condition READ on its way to `false`: only the row (and `objectContext`) is a
|
|
34
|
+
* refusal of the state, 409 Conflict; a read of `initiatorIds`, `initiatorUserContext` or `inputDto` may be a refusal of
|
|
35
|
+
* the caller, 403 Forbidden. `&&` stops at the first false operand, so write the state check FIRST
|
|
36
|
+
* (`currentObject.status === PENDING && currentObject.requestedByUserId !== initiatorIds.userId`): a refusal on the
|
|
37
|
+
* status then never reads the caller and answers 409. On a CREATE-shaped operation `currentObject` is the request body, so
|
|
38
|
+
* a refusal there is never a state conflict: 403.
|
|
39
|
+
*
|
|
33
40
|
* - `currentObject` — the row as it stands. On a list row only its summary fields and the variant's
|
|
34
41
|
* `enabledConditionFields` are present.
|
|
35
42
|
* - `initiatorIds.userId` — the person asking (absent for a machine principal). Compare it with an owner field to offer an
|
package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md
CHANGED
|
@@ -45,7 +45,7 @@ moves the business does not allow.
|
|
|
45
45
|
* read from the row. ACCEPT and DECLINE arriving at the same moment on one SENT quote both pass the
|
|
46
46
|
* condition, but only the first write finds the quote still SENT. The second matches no row and is
|
|
47
47
|
* refused with 409 `version_conflict` (re-read the quote and decide again). One after the other, the second is
|
|
48
|
-
* refused by the condition itself (
|
|
48
|
+
* refused by the condition itself (409 `service_resource_operation_disabled`: it read only the row). Nothing is declared for
|
|
49
49
|
* this: the condition is the declaration.
|
|
50
50
|
*/
|
|
51
51
|
export enum Quote_Status {
|
|
@@ -196,7 +196,7 @@ What each part earns:
|
|
|
196
196
|
`enabledCondition` read from the row (here `status`). ACCEPT and DECLINE arriving together on one SENT
|
|
197
197
|
quote both pass the condition, but only the first write finds the quote still SENT. The second matches no
|
|
198
198
|
row and is refused with 409 `version_conflict` (the answer an `If-Match` conflict gets: re-read the quote
|
|
199
|
-
and decide again), and nothing it would have written lands. One after the other, the second is refused by the condition (
|
|
200
|
-
`service_resource_operation_disabled
|
|
199
|
+
and decide again), and nothing it would have written lands. One after the other, the second is refused by the condition (409
|
|
200
|
+
`service_resource_operation_disabled`, since the condition read only the row). Nothing extra is declared for this, and nothing belongs in
|
|
201
201
|
application code: read the fields the decision depends on in the condition, and they become the write's
|
|
202
202
|
precondition. An edit to a field the condition never read (the title) does not block a transition.
|
|
@@ -482,7 +482,7 @@ const CHANGE_STATUS_ACTION = {
|
|
|
482
482
|
surface: ResourceOperationFrontendSurface.EMBEDDED,
|
|
483
483
|
iconOverride: CircleDot,
|
|
484
484
|
actionPresentation: ResourceOperationActionPresentation.INLINE,
|
|
485
|
-
// Explicit ORDER in the bar. Status is the verb reached for most often on a todo, so it leads;
|
|
485
|
+
// Explicit ORDER in the bar. Status is the verb reached for most often on a todo, so it leads; the move follows (MOVE_TO_LIST, 7).
|
|
486
486
|
// Without this the bar orders by registration, which is an artefact of how the config file was written rather than
|
|
487
487
|
// of how the actions are used — and `actionDisclosure` caps the bar at three, so ordering decides WHICH three survive.
|
|
488
488
|
// Lower comes first, and it must be BELOW 10: that is Edit's default, and every custom operation built on UPDATE
|
|
@@ -649,11 +649,17 @@ const REOPEN_ACTION = {
|
|
|
649
649
|
// foreign key declared to `todoLists`), so "Move to ▾" lists the lists and picking one moves the todo.
|
|
650
650
|
// It is named apart from the route's `todoListId`, the SOURCE list when the todo is opened inside it
|
|
651
651
|
// (see `Todos_MoveToListRequestDto`). It is how a capture leaves the Inbox for its week (#2622).
|
|
652
|
+
//
|
|
653
|
+
// Priority 7, BELOW 10, for CHANGE_STATUS's reason: Edit defaults to 10 and every UPDATE-like custom verb (Make
|
|
654
|
+
// recurring, Unassign…) inherits it, and the detail bar keeps three. At 30 the pick never held a slot: a todo's
|
|
655
|
+
// header read Change status, Edit, Make recurring, and "Move to" sat in the `…` menu, where a DROPDOWN degrades to
|
|
656
|
+
// the overlay form that marks no current list (#3861). Moving is what a todo in the Inbox is opened for, so it
|
|
657
|
+
// takes the slot Make recurring held; it follows the status verbs (5, 6) and leads Edit.
|
|
652
658
|
[Todos_Operations.MOVE_TO_LIST, {
|
|
653
659
|
surface: ResourceOperationFrontendSurface.EMBEDDED,
|
|
654
660
|
iconOverride: FolderInput,
|
|
655
661
|
actionPresentation: ResourceOperationActionPresentation.DROPDOWN,
|
|
656
|
-
displayPriority:
|
|
662
|
+
displayPriority: 7,
|
|
657
663
|
}],
|
|
658
664
|
// These three pair off with ASSIGN and with each other: exactly one of
|
|
659
665
|
// ASSIGN/UNASSIGN applies to a todo, and exactly one of
|
|
@@ -138,7 +138,11 @@ const backendModule: BackendDomainModule = {
|
|
|
138
138
|
],
|
|
139
139
|
// A signed webhook from a client's system that creates a todo (#1596) — `POST /webhooks/app/todo-intake`;
|
|
140
140
|
// and an email to an organization's address that creates one and answers on the thread (#1600, #1630).
|
|
141
|
-
|
|
141
|
+
// and what Teams sends the application's bot or an organization's own bot (#2663) — `POST /webhooks/microsoft-teams-bot/messages`.
|
|
142
|
+
inboundHandlers: [todoIntakeInboundHandler, todoEmailIntakeHandler, todoEmailScreenedHandler, todoEmailScreeningHandler, teamsBotInboundHandler],
|
|
143
|
+
// An agent's answer to a Teams conversation goes back through the bot it was sent to; startup refuses the Teams
|
|
144
|
+
// messages handler without it.
|
|
145
|
+
chatReplyHandlers: [teamsChatReplyHandler],
|
|
142
146
|
// NOT listed: `todoSmsStatusHandler` (`./inbound/todos.sms-status.inbound-channel-handler`, #3394), a member's todo
|
|
143
147
|
// status by text. An SMS channel handler stops the backend at startup while the SMS channel does not receive, and
|
|
144
148
|
// Your Application keeps the SMS capability off (no vendor account, 2026-10-02). Enabling SMS with a provider whose
|
|
@@ -323,6 +323,12 @@ const ALLOWED_BARE_SPECIFIERS: ReadonlySet<string> = new Set([
|
|
|
323
323
|
*/
|
|
324
324
|
'node:module',
|
|
325
325
|
'node:url',
|
|
326
|
+
/**
|
|
327
|
+
* `node:crypto` — `websiteContentSecurityPolicy()` (`content-security-policy.integration.ts`, on the `astro.ts`
|
|
328
|
+
* sub-entry, #3830) names each inline script it moves out of a built page by the SHA-256 of its content. It runs in
|
|
329
|
+
* `astro.config.ts` after the build, never in an island; pinned SSR-only below.
|
|
330
|
+
*/
|
|
331
|
+
'node:crypto',
|
|
326
332
|
/**
|
|
327
333
|
* `sharp` — measures a blog post's cover from the site's `public/` at build time (`blog-post-cover.resolver.ts`, on
|
|
328
334
|
* the `astro.ts` sub-entry, #2723), so a cover reaches `WebsiteImage` with its real size. A native library: loaded
|
|
@@ -256,6 +256,12 @@ const ALLOWED_BARE_SPECIFIERS: ReadonlySet<string> = new Set([
|
|
|
256
256
|
*/
|
|
257
257
|
'node:module',
|
|
258
258
|
'node:url',
|
|
259
|
+
/**
|
|
260
|
+
* `node:crypto` — `websiteContentSecurityPolicy()` (`content-security-policy.integration.ts`, on the `astro.ts`
|
|
261
|
+
* sub-entry, #3830) names each inline script it moves out of a built page by the SHA-256 of its content. It runs in
|
|
262
|
+
* `astro.config.ts` after the build, never in an island; pinned SSR-only below.
|
|
263
|
+
*/
|
|
264
|
+
'node:crypto',
|
|
259
265
|
/**
|
|
260
266
|
* `sharp` — measures a blog post's cover from the site's `public/` at build time (`blog-post-cover.resolver.ts`, on
|
|
261
267
|
* the `astro.ts` sub-entry, #2723), so a cover reaches `WebsiteImage` with its real size. A native library: loaded
|