@wildo-ai/framework-knowledge 1.1.5 → 1.1.6
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 +14 -0
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +8 -0
- package/dist/claude-marketplace/plugins/wildo/agents/wildo-deriver.md +41 -0
- package/dist/claude-marketplace/plugins/wildo/hooks/hooks.json +18 -0
- package/dist/claude-marketplace/plugins/wildo/monitors/monitors.json +8 -0
- package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +38 -0
- package/dist/{knowledge/skills/journey-run/references/framework-playbook-approval-policy.md → claude-marketplace/plugins/wildo/references/approval-and-failure-policy.md} +10 -8
- package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +29 -0
- package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +61 -0
- package/dist/{knowledge/skills/journey-run → claude-marketplace/plugins/wildo}/references/expert-personas-and-deliberations.md +8 -8
- package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +67 -0
- package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +43 -0
- package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +70 -0
- package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +38 -0
- package/dist/claude-marketplace/plugins/wildo/skills/doctor/SKILL.md +23 -0
- package/dist/claude-marketplace/plugins/wildo/skills/next/SKILL.md +39 -0
- package/dist/claude-marketplace/plugins/wildo/skills/run/SKILL.md +39 -0
- package/dist/claude-marketplace/plugins/wildo/skills/start/SKILL.md +38 -0
- package/dist/claude-marketplace/plugins/wildo/skills/status/SKILL.md +38 -0
- package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +37 -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 +320 -11
- 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.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +0 -3
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts +12 -2
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +33 -2
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +8 -5
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +55 -10
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +1 -6
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +1 -6
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -4
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts +10 -3
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js +7 -3
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +8 -3
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +7 -3
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +9 -4
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +3 -2
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +4 -3
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js +1 -3
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +10 -3
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +8 -3
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts +12 -5
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js +33 -5
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts +59 -0
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js +72 -0
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +66 -0
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +115 -0
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts +50 -0
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +54 -0
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +36 -17
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.js +67 -17
- package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts +45 -0
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js +46 -0
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +11 -3
- package/dist/esm/playbooks/top_down.vision-elicitation/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 +8 -8
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +0 -3
- package/dist/knowledge/playbooks/bottom_up.build/method.md +4 -2
- package/dist/knowledge/playbooks/bottom_up.build/playbook.json +31 -7
- package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +134 -26
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +7 -4
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +84 -29
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -7
- package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +12 -23
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +2 -7
- package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +12 -14
- package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -2
- package/dist/knowledge/playbooks/bottom_up.conception/method.md +20 -2
- package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +15 -7
- package/dist/knowledge/playbooks/bottom_up.documentation-plan/method.md +8 -6
- package/dist/knowledge/playbooks/bottom_up.documentation-plan/playbook.json +11 -4
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +2 -4
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +3 -4
- package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +18 -2
- package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +1 -2
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +2 -4
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +8 -5
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +16 -2
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +3 -3
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +1 -3
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +1 -2
- package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +8 -7
- package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +11 -4
- package/dist/knowledge/playbooks/cross_cutting.application-creation/playbook.json +27 -5
- package/dist/knowledge/playbooks/cross_cutting.compliance/playbook.json +1 -4
- package/dist/knowledge/playbooks/cross_cutting.feature-development/method.md +42 -0
- package/dist/knowledge/playbooks/cross_cutting.feature-development/playbook.json +73 -0
- package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +46 -0
- package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +108 -0
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +112 -21
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +7 -2
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +2 -4
- package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +48 -0
- package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +66 -0
- package/dist/knowledge/playbooks/refinement.governance-document-candidate/method.md +6 -0
- package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +0 -4
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +1 -2
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +1 -3
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +2 -4
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -2
- package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +1 -3
- package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +5 -3
- package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +2 -4
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +1 -3
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +0 -4
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +2 -4
- package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +1 -3
- package/dist/knowledge/playbooks/top_down.definition/method.md +7 -4
- package/dist/knowledge/playbooks/top_down.definition/playbook.json +52 -7
- package/dist/knowledge/playbooks/top_down.expert-personas/method.md +1 -1
- package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +2 -4
- package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +72 -0
- package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +57 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +0 -1
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +0 -1
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +0 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +2 -4
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +1 -2
- package/dist/knowledge/playbooks/top_down.phase-gate/method.md +1 -1
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +2 -6
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +17 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +2 -5
- package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +1 -3
- package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +15 -7
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +2 -4
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +2 -4
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +1 -2
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +7 -3
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +12 -5
- package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +212 -0
- package/dist/knowledge/references/backend.inbound-handlers.agents.md +45 -0
- package/dist/knowledge/references/backend.inbound-handlers.definition.md +218 -0
- package/dist/knowledge/references/build-plan.task-graph.config.md +71 -6
- package/dist/knowledge/references/capability-composition.config.md +20 -1
- package/dist/knowledge/references/cli.market.generate-command.md +18 -2
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +7 -22
- package/dist/knowledge/references/engine.saas-technical-doc.provider-component.slot.md +83 -0
- package/dist/knowledge/references/example.authorization.service-provider-organization-wide-access.md +12 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -0
- package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +7 -3
- package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +7 -0
- package/dist/knowledge/references/example.config.app-shell.full.md +11 -0
- package/dist/knowledge/references/example.config.backend.billing-enable.md +14 -0
- package/dist/knowledge/references/example.config.backend.inbound-email.md +14 -0
- package/dist/knowledge/references/example.config.backend.required-floors.md +7 -0
- package/dist/knowledge/references/example.config.navigation.full.md +45 -2
- package/dist/knowledge/references/example.config.provider-usage-pricing.md +36 -0
- package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +5 -3
- package/dist/knowledge/references/example.config.provider.backend-scope-inbound-email.md +16 -0
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.md +23 -0
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +36 -0
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +26 -3
- package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +1 -1
- package/dist/knowledge/references/example.inbound.application-endpoint-handler.md +72 -0
- package/dist/knowledge/references/example.inbound.email-channel-handler.md +47 -0
- package/dist/knowledge/references/example.inbound.email-to-todo.md +150 -0
- package/dist/knowledge/references/example.infra.environment-config.local.md +14 -30
- package/dist/knowledge/references/example.layout-3d.own-layout.md +16 -0
- package/dist/knowledge/references/example.layout-3d.registration.md +15 -0
- package/dist/knowledge/references/example.module.companion-exports.full.md +8 -13
- package/dist/knowledge/references/example.module.relationships.discriminator.md +2 -2
- package/dist/knowledge/references/example.organizations.serves-as-provider.md +12 -0
- package/dist/knowledge/references/example.provider.address-lookup.adapter.md +64 -0
- package/dist/knowledge/references/example.provider.backend-module-shape.md +3 -0
- package/dist/knowledge/references/example.provider.frontend-app.module.md +9 -0
- package/dist/knowledge/references/example.provider.frontend-facet.package-module.md +85 -0
- package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +14 -13
- package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +18 -0
- package/dist/knowledge/references/example.provider.operation.backend-typed-client.md +11 -11
- package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +5 -0
- package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +2 -0
- package/dist/knowledge/references/example.resource.retention-binding.closure-event.md +21 -0
- package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +1 -2
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +24 -6
- package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +36 -25
- package/dist/knowledge/references/example.resource.work-unit.declaration.md +13 -0
- package/dist/knowledge/references/example.spec.composite-view.workspace.md +0 -12
- package/dist/knowledge/references/example.views.app-level.composite-views-config.md +1 -1
- package/dist/knowledge/references/example.views.chart-view.resource-owned.md +27 -0
- package/dist/knowledge/references/example.views.composite-view.workspace.md +4 -1
- package/dist/knowledge/references/example.website.page.manifest.md +30 -0
- package/dist/knowledge/references/experience-plan.config.md +11 -4
- package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +20 -0
- package/dist/knowledge/references/external-connectors.backend.provider-augmentation.md +75 -0
- package/dist/knowledge/references/external-connectors.frontend-provider-component-declaration.md +85 -0
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +52 -0
- package/dist/knowledge/references/external-connectors.models.connection-rate-budgets.md +113 -0
- package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +165 -0
- package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +133 -0
- package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +44 -0
- package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +21 -0
- package/dist/knowledge/references/external-connectors.provider-component-load-state.md +45 -0
- package/dist/knowledge/references/external-connectors.provider-component-loader-contribution.md +32 -0
- package/dist/knowledge/references/external-connectors.provider-component-registry.md +190 -0
- package/dist/knowledge/references/external-connectors.techdoc.frontend-provider-module.md +91 -0
- package/dist/knowledge/references/external-connectors.website.frontend-provider-module.md +91 -0
- package/dist/knowledge/references/integration-plan.config.md +34 -2
- package/dist/knowledge/references/market.alternative.config.md +1 -1
- package/dist/knowledge/references/market.buying-journey.config.md +1 -1
- package/dist/knowledge/references/market.category.config.md +1 -1
- package/dist/knowledge/references/market.channel.config.md +1 -1
- package/dist/knowledge/references/market.feature-benefit.config.md +1 -1
- package/dist/knowledge/references/market.gain.config.md +1 -1
- package/dist/knowledge/references/market.icp.config.md +1 -1
- package/dist/knowledge/references/market.job.config.md +1 -1
- package/dist/knowledge/references/market.message-template.config.md +1 -1
- package/dist/knowledge/references/market.objection.config.md +1 -1
- package/dist/knowledge/references/market.pain.config.md +1 -1
- package/dist/knowledge/references/market.persona.config.md +1 -1
- package/dist/knowledge/references/market.positioning.config.md +1 -1
- package/dist/knowledge/references/market.proof.config.md +1 -1
- package/dist/knowledge/references/market.references.weighted-edges.md +7 -0
- package/dist/knowledge/references/market.tone-of-voice.config.md +1 -1
- package/dist/knowledge/references/market.trigger.config.md +1 -1
- package/dist/knowledge/references/placement-plan.config.md +7 -1
- package/dist/knowledge/references/platform.config.backing-services.md +15 -15
- package/dist/knowledge/references/platform.config.infra-provider-resolution.md +57 -57
- package/dist/knowledge/references/presets.3d.frame-style-overrides.md +134 -0
- package/dist/knowledge/references/presets.3d.layout-contract.md +213 -0
- package/dist/knowledge/references/presets.3d.register-layout.md +95 -0
- package/dist/knowledge/references/presets.models.labelling.sections.md +5 -0
- package/dist/knowledge/references/presets.models.shell-region.md +47 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -0
- package/dist/knowledge/references/saas.backend.actor-execution-decision-record.md +41 -0
- package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +1 -1
- package/dist/knowledge/references/saas.backend.authorization.role-ceiling.md +7 -6
- package/dist/knowledge/references/saas.backend.compliance.governed-documents-pdf-template.md +370 -0
- package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +7 -0
- package/dist/knowledge/references/saas.backend.domain-module.md +93 -15
- package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-declaration.md +66 -0
- package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-schedule.md +31 -0
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +200 -0
- package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +2 -0
- package/dist/knowledge/references/saas.backend.pdf-template.collection-definition.md +73 -0
- package/dist/knowledge/references/saas.backend.providers.connection-target-credential-resolution.md +33 -9
- package/dist/knowledge/references/saas.backend.submission-challenge.md +118 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +98 -0
- package/dist/knowledge/references/saas.backend.system-of-record-action-runner.md +73 -0
- package/dist/knowledge/references/saas.config.providers.augmentations.md +61 -0
- package/dist/knowledge/references/saas.config.providers.packages.md +59 -0
- package/dist/knowledge/references/saas.config.providers.shared-connections.md +84 -0
- package/dist/knowledge/references/saas.external-data.admin-endpoints.md +56 -2
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +2 -2
- package/dist/knowledge/references/saas.frontend.app-shell.building-blocks.md +250 -0
- package/dist/knowledge/references/saas.frontend.billing-context.md +25 -2
- package/dist/knowledge/references/saas.frontend.chart-view.resource-chart-data.md +92 -0
- package/dist/knowledge/references/saas.frontend.consent-based-provider-activation.md +22 -0
- package/dist/knowledge/references/saas.frontend.form-field-address.lookup-slot.md +74 -0
- package/dist/knowledge/references/saas.frontend.linked-conversations-embed.md +60 -0
- package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +7 -5
- package/dist/knowledge/references/saas.frontend.notifications.publish-badge-count.md +60 -0
- package/dist/knowledge/references/saas.frontend.providers.execute-operation.md +17 -2
- package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +49 -0
- package/dist/knowledge/references/saas.frontend.related-resource-sections.md +8 -1
- package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +9 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +100 -5
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +25 -1
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +61 -0
- package/dist/knowledge/references/saas.market.generation-agent.md +0 -1
- package/dist/knowledge/references/saas.models.agent-work-capture-settings.md +34 -0
- package/dist/knowledge/references/saas.models.agent-work-decision-surface.md +45 -0
- package/dist/knowledge/references/saas.models.agent-work-decision-vocabulary.md +107 -0
- package/dist/knowledge/references/saas.models.agent-work-output-review.md +36 -0
- package/dist/knowledge/references/saas.models.agent-work-override-rate.md +50 -0
- package/dist/knowledge/references/saas.models.agent-work-review-config.md +24 -0
- package/dist/knowledge/references/saas.models.audit-trails.actor-attribution.md +97 -0
- package/dist/knowledge/references/saas.models.audit.trail-config.md +15 -9
- package/dist/knowledge/references/saas.models.auth.service-provider-client-authentication.md +169 -0
- package/dist/knowledge/references/saas.models.authorization.administrative-continuity-codes.md +8 -0
- package/dist/knowledge/references/saas.models.billing.catalog-vocabularies.md +54 -1
- package/dist/knowledge/references/saas.models.billing.referral-program.md +47 -0
- package/dist/knowledge/references/saas.models.config.organization-types.md +74 -0
- package/dist/knowledge/references/saas.models.config.tenant-teardown.md +31 -14
- package/dist/knowledge/references/saas.models.conversation-threads.md +242 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +4 -4
- package/dist/knowledge/references/saas.models.engine-capabilities.md +12 -0
- package/dist/knowledge/references/saas.models.engine-capabilities.required-provider-floor.md +5 -1
- package/dist/knowledge/references/saas.models.evaluation-dataset-export.md +39 -0
- package/dist/knowledge/references/saas.models.evaluation-export-authorization.md +38 -0
- package/dist/knowledge/references/saas.models.external-data-pipeline.md +667 -6
- package/dist/knowledge/references/saas.models.flows-actors.autonomous-agents-vocabulary.md +98 -0
- package/dist/knowledge/references/saas.models.flows-actors.human-decision-vocabulary.md +52 -0
- package/dist/knowledge/references/saas.models.flows-actors.review-calendar.md +42 -0
- package/dist/knowledge/references/saas.models.flows-actors.review-deadline-vocabulary.md +84 -0
- package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +69 -0
- package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +72 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +812 -29
- package/dist/knowledge/references/saas.models.http-api-binding.rest-write-operations.md +81 -0
- package/dist/knowledge/references/saas.models.human-decision-review-marker.md +20 -0
- package/dist/knowledge/references/saas.models.inbound-channels.md +277 -0
- package/dist/knowledge/references/saas.models.inbound-email-domains.md +101 -0
- package/dist/knowledge/references/saas.models.inbound-email.md +111 -0
- package/dist/knowledge/references/saas.models.model-cost-accounting-config.md +28 -0
- package/dist/knowledge/references/saas.models.model-cost-summary.md +87 -0
- package/dist/knowledge/references/saas.models.navigation.layout.md +11 -7
- package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +32 -23
- package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +8 -4
- package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +22 -20
- package/dist/knowledge/references/saas.models.notifications.badge-vocabularies.md +14 -0
- package/dist/knowledge/references/saas.models.notifications.targets.md +20 -12
- package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +61 -34
- package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +9 -0
- package/dist/knowledge/references/saas.models.organizations.service-provider-activity-feed.md +121 -0
- package/dist/knowledge/references/saas.models.organizations.service-provider-capability-grants.md +152 -0
- package/dist/knowledge/references/saas.models.organizations.service-provider-client-controls.md +49 -0
- package/dist/knowledge/references/saas.models.organizations.service-provider-relationships.md +567 -0
- package/dist/knowledge/references/saas.models.privacy.legal-holds.md +172 -0
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +104 -0
- package/dist/knowledge/references/saas.models.privacy.retention-binding.md +103 -0
- package/dist/knowledge/references/saas.models.privacy.retention-enforcement-record.md +120 -0
- package/dist/knowledge/references/saas.models.privacy.retention-schedule.md +147 -0
- package/dist/knowledge/references/saas.models.privacy.statutory-retention-ground.md +50 -0
- package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +388 -0
- package/dist/knowledge/references/saas.models.provider-address-lookup-contract.md +139 -0
- package/dist/knowledge/references/saas.models.provider-address-lookup-declaration.md +61 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +34 -0
- package/dist/knowledge/references/saas.models.provider-credential-identity.md +67 -0
- package/dist/knowledge/references/saas.models.provider-usage-pricing-authority.md +139 -0
- package/dist/knowledge/references/saas.models.providers.browser-operation-policy.md +61 -0
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +98 -13
- package/dist/knowledge/references/saas.models.providers.scope-reauthorization.md +57 -0
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +122 -28
- package/dist/knowledge/references/saas.models.resource-config.operation-submission-challenge.md +54 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +6 -0
- package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +8 -0
- package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +82 -0
- package/dist/knowledge/references/saas.models.system-of-record-actions.md +226 -0
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +461 -0
- package/dist/knowledge/references/saas.models.systems-of-record.facet-augmentation.md +63 -0
- package/dist/knowledge/references/saas.models.systems-of-record.md +242 -7
- package/dist/knowledge/references/saas.models.work-attribution-vocabulary.md +109 -0
- package/dist/knowledge/references/saas.models.work-unit-ref.md +28 -0
- package/dist/knowledge/references/saas.public-runtime.contract.md +75 -7
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +20 -0
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +106 -13
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +14 -13
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +36 -14
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +4 -3
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +4 -4
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-software-application.md +71 -0
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +6 -4
- package/dist/knowledge/references/saas.specifications.compliance.retention-enforcement-state.md +32 -0
- package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +14 -2
- package/dist/knowledge/references/saas.specifications.processor-register.md +77 -0
- package/dist/knowledge/references/saas.specifications.recipient-disclosures.md +71 -0
- package/dist/knowledge/references/saas.specifications.recipient-population.md +549 -0
- package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +112 -45
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +13 -1
- package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +17 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +16 -0
- package/dist/knowledge/references/saas.specifications.subject-data-recipients.md +98 -0
- package/dist/knowledge/references/saas.website.astro.bridge.md +32 -9
- package/dist/knowledge/references/saas.website.astro.head-renderer.md +1 -1
- package/dist/knowledge/references/saas.website.astro.label-loader.md +7 -4
- package/dist/knowledge/references/saas.website.astro.robots-renderer.md +15 -15
- package/dist/knowledge/references/saas.website.astro.site-context.md +5 -2
- package/dist/knowledge/references/saas.website.blog.bridge.md +17 -4
- package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +61 -0
- package/dist/knowledge/references/saas.website.config.site-context-loader.md +154 -0
- package/dist/knowledge/references/saas.website.consent.banner.md +10 -10
- package/dist/knowledge/references/saas.website.design-tokens.colors.md +7 -4
- package/dist/knowledge/references/saas.website.design-tokens.radius.md +1 -1
- package/dist/knowledge/references/saas.website.factories.define-section.md +3 -3
- package/dist/knowledge/references/saas.website.page-layout.component.md +5 -2
- package/dist/knowledge/references/saas.website.pricing-offer-structured-data.md +140 -0
- package/dist/knowledge/references/saas.website.provider-component.slot.md +99 -0
- package/dist/knowledge/references/saas.website.root-config.schema.md +6 -6
- package/dist/knowledge/references/saas.website.runtime.context.md +23 -4
- package/dist/knowledge/references/saas.website.sections.definition-schema.md +14 -7
- package/dist/knowledge/references/saas.website.seo.robots-config.md +4 -3
- package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +7 -5
- package/dist/knowledge/references/saas.website.submission-challenge.md +77 -0
- package/dist/knowledge/references/saas.website.use-pricing-catalog.hook.md +36 -0
- package/dist/knowledge/references/saas.website.use-runtime.hook.md +3 -2
- package/dist/knowledge/references/website-plan.config.md +39 -6
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +2 -1
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +21 -0
- package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +1 -2
- package/dist/knowledge/references/zod.decorators.file-schema.md +11 -10
- package/dist/knowledge/references/zod.decorators.file-vocabularies.md +7 -4
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +8 -2
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +5 -1
- package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +5 -1
- package/dist/knowledge/references/zod.factories.address.md +7 -7
- package/dist/knowledge/references/zod.factories.code.md +2 -2
- package/dist/knowledge/references/zod.factories.duration.md +4 -4
- package/dist/knowledge/references/zod.factories.money.md +3 -3
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +1238 -54
- package/dist/knowledge/registries/playbooks.json +81 -109
- package/dist/knowledge/registries/source-tags.json +3191 -1126
- package/dist/knowledge/rules/live-context-door.md +29 -0
- package/dist/knowledge/skills/INDEX.md +27 -24
- package/dist/knowledge/skills/agent-work-review/SKILL.md +141 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-capture-settings-api.md +38 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-output-review-api.md +40 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-override-rate-api.md +54 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-config-api.md +28 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +108 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-vocabulary-api.md +111 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-dataset-export-api.md +43 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-export-authorization-api.md +42 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +31 -0
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +1 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +1 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +9 -0
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +6 -0
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +94 -16
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +21 -8
- package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +7 -0
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +13 -5
- package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +30 -6
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +160 -32
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +20 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +14 -2
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +88 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +112 -14
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +209 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-population.md +577 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +549 -0
- package/dist/knowledge/skills/config-app-shell/SKILL.md +21 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +2 -2
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-building-blocks-api.md +276 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-shell-region-markers-api.md +66 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +1 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +114 -16
- package/dist/knowledge/skills/config-navigation/references/choosing-a-navigation-shape.md +314 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +11 -7
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +29 -5
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +40 -27
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +22 -20
- package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +112 -5
- package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +10 -10
- package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +1 -1
- package/dist/knowledge/skills/config-saas/SKILL.md +3 -1
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +7 -0
- package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +21 -11
- package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +5 -1
- package/dist/knowledge/skills/config-saas/references/framework-connection-target-credentials.md +59 -9
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +46 -0
- package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +251 -12
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +8 -0
- package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +81 -0
- package/dist/knowledge/skills/config-saas-backend/references/framework-tenant-teardown-api.md +37 -15
- package/dist/knowledge/skills/configure-billing/SKILL.md +64 -24
- package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +35 -2
- package/dist/knowledge/skills/configure-billing/references/example-backend-billing-enable-block.md +14 -0
- package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +3 -0
- package/dist/knowledge/skills/configure-billing/references/framework-billing-frontend-api.md +25 -2
- package/dist/knowledge/skills/configure-billing/references/framework-product-catalog-api.md +73 -1
- package/dist/knowledge/skills/configure-billing/references/framework-referral-program.md +110 -0
- package/dist/knowledge/skills/configure-billing/references/framework-subscription-behavior-policy.md +27 -12
- package/dist/knowledge/skills/configure-coding-agent/SKILL.md +11 -2
- package/dist/knowledge/skills/configure-coding-agent/references/agent-selection.md +26 -2
- package/dist/knowledge/skills/email-add-template/SKILL.md +61 -24
- package/dist/knowledge/skills/email-add-template/references/framework-email-attachments-and-limits.md +5 -2
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -0
- package/dist/knowledge/skills/email-labels-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/email-template-authoring/SKILL.md +1 -0
- package/dist/knowledge/skills/engine-component-registration/SKILL.md +1 -0
- package/dist/knowledge/skills/engine-product-definitions/SKILL.md +6 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +27 -3
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +180 -0
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +56 -0
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-autonomous-agent-api.md +208 -0
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-inbound-agents-api.md +51 -0
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/tool-posture.md +27 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +31 -4
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +26 -3
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-audit-agent-attribution-api.md +148 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +287 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +202 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +93 -15
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +96 -11
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +2 -1
- package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +1 -0
- package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +1 -0
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -2
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +14 -9
- package/dist/knowledge/skills/guidance-onboarding-authoring/SKILL.md +1 -0
- package/dist/knowledge/skills/i18n-label-generation/SKILL.md +1 -0
- package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +5 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +11 -9
- package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +5 -0
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +8 -1
- package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +5 -0
- package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +5 -0
- package/dist/knowledge/skills/inbound-channels/SKILL.md +301 -0
- package/dist/knowledge/skills/inbound-channels/references/email-channel.md +133 -0
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +800 -0
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-email-api.md +222 -0
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +231 -0
- package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +135 -0
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +297 -0
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +150 -44
- package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +83 -74
- package/dist/knowledge/skills/layout-3d-adoption/SKILL.md +176 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-frame-style-overrides-api.md +141 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-contract-api.md +223 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-registration-api.md +103 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-building-blocks-api.md +256 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-region-marker-api.md +52 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/layouts-and-transitions.md +29 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/manual-adoption-and-removal.md +25 -0
- package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +32 -1
- package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +2 -1
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +36 -4
- package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +2 -1
- package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +1 -1
- package/dist/knowledge/skills/market-alternatives/SKILL.md +3 -2
- package/dist/knowledge/skills/market-authoring-overview/SKILL.md +1 -0
- package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +7 -0
- package/dist/knowledge/skills/market-category/SKILL.md +2 -1
- package/dist/knowledge/skills/market-channels/SKILL.md +2 -1
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +7 -4
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +6 -4
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +28 -13
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +18 -3
- package/dist/knowledge/skills/market-icp/SKILL.md +2 -1
- package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +4 -3
- package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1 -1
- package/dist/knowledge/skills/market-persona/SKILL.md +2 -1
- package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +1 -1
- package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +3 -2
- package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +1 -0
- package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1 -0
- package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +2 -1
- package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +3 -2
- package/dist/knowledge/skills/milestones-and-celebrations/SKILL.md +1 -0
- package/dist/knowledge/skills/minion-authoring/SKILL.md +5 -1
- package/dist/knowledge/skills/model-cost-attribution/SKILL.md +143 -0
- package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +211 -0
- package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-summary-api.md +95 -0
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-attribution-api.md +117 -0
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +677 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +17 -16
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +6 -4
- package/dist/knowledge/skills/module-registration/SKILL.md +2 -1
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +93 -15
- package/dist/knowledge/skills/module-registration/references/framework-notification-badges-api.md +86 -1
- package/dist/knowledge/skills/module-relationships/SKILL.md +3 -2
- package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +34 -2
- package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-collection-template-api.md +447 -0
- package/dist/knowledge/skills/provider-address-lookup/SKILL.md +207 -0
- package/dist/knowledge/skills/provider-address-lookup/references/framework-address-field-lookup-slot-api.md +82 -0
- package/dist/knowledge/skills/provider-address-lookup/references/framework-address-lookup-contract-api.md +214 -0
- package/dist/knowledge/skills/provider-address-lookup/references/framework-browser-operation-policy-api.md +143 -0
- package/dist/knowledge/skills/provider-address-lookup/references/google-places-setup.md +73 -0
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +272 -33
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-augmentation-api.md +227 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-credential-identity-api.md +101 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +245 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +88 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-package-allow-list-api.md +111 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +309 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +132 -23
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +399 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +29 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +115 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-provider-component-registry-api.md +386 -0
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +258 -0
- package/dist/knowledge/skills/provider-frontend-module/references/framework-frontend-facet-contracts-api.md +463 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +61 -0
- package/dist/knowledge/skills/provider-operation-calls/SKILL.md +75 -24
- package/dist/knowledge/skills/provider-operation-calls/references/browser-door-answers.md +3 -3
- package/dist/knowledge/skills/provider-operation-calls/references/framework-browser-operation-policy-api.md +61 -0
- package/dist/knowledge/skills/provider-operation-calls/references/framework-connection-rate-budgets-api.md +176 -0
- package/dist/knowledge/skills/provider-operation-calls/references/framework-frontend-execute-operation-api.md +17 -2
- package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-operation-executor-api.md +15 -0
- package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-scope-reauthorization-api.md +127 -0
- package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +25 -0
- package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +6 -0
- package/dist/knowledge/skills/resource-add-field/SKILL.md +1 -0
- package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +1 -2
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +105 -6
- package/dist/knowledge/skills/resource-add-module/SKILL.md +1 -0
- package/dist/knowledge/skills/resource-add-module/references/framework-composition-scenarios-api.md +2 -1
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +3 -0
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +124 -30
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +1 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-administrative-continuity-codes-api.md +8 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-authority-audit-interpretation.md +9 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +17 -1
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +124 -30
- package/dist/knowledge/skills/resource-config-wiring/references/framework-role-ceiling-api.md +7 -6
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +142 -34
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +98 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +86 -52
- package/dist/knowledge/skills/resource-custom-view/SKILL.md +1 -0
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +100 -5
- package/dist/knowledge/skills/resource-external-data/SKILL.md +1026 -28
- package/dist/knowledge/skills/resource-external-data/references/declared-expressions.md +144 -0
- package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +68 -0
- package/dist/knowledge/skills/resource-external-data/references/facet-augmentations.md +154 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +686 -11
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +904 -31
- package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +166 -6
- package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +152 -0
- package/dist/knowledge/skills/resource-external-data/references/odata-v2-sources.md +60 -0
- package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +179 -0
- package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +1 -1
- package/dist/knowledge/skills/resource-external-data/references/provenance-cue.md +63 -0
- package/dist/knowledge/skills/resource-external-data/references/rate-budgets-and-pacing.md +122 -0
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +745 -0
- package/dist/knowledge/skills/resource-external-data/references/remote-references.md +85 -0
- package/dist/knowledge/skills/resource-external-data/references/rest-keyset-sources.md +85 -0
- package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +442 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +1 -0
- package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +1 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +12 -0
- package/dist/knowledge/skills/resource-retention-binding/SKILL.md +186 -0
- package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +200 -0
- package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-binding-api.md +111 -0
- package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-enforcement-records-api.md +173 -0
- package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-schedule-api.md +155 -0
- package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +139 -0
- package/dist/knowledge/skills/resource-retention-binding/references/start-point-decisions.md +55 -0
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +2 -2
- package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +1 -2
- package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +3 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +2 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-erasure-scrub-treatments-api.md +28 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +5 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +34 -30
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +5 -1
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +101 -42
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +21 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +1 -2
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +125 -6
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +8 -2
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +57 -1
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +61 -1
- package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +110 -9
- package/dist/knowledge/skills/seeding-authoring/SKILL.md +1 -0
- package/dist/knowledge/skills/seeding-operations/SKILL.md +1 -0
- package/dist/knowledge/skills/service-provider-relationships/SKILL.md +455 -0
- package/dist/knowledge/skills/service-provider-relationships/references/framework-organization-types-api.md +270 -0
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-activity-feed-api.md +129 -0
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-capability-grants-api.md +161 -0
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-client-authentication-api.md +224 -0
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-relationships-api.md +576 -0
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +1 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +61 -0
- package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +43 -37
- package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +15 -14
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +14 -16
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +6 -4
- package/dist/knowledge/skills/spec-component-update/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +20 -21
- package/dist/knowledge/skills/spec-family-update/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-feature-update/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-resource-update/SKILL.md +13 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +158 -46
- package/dist/knowledge/skills/spec-update-after-change/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +17 -0
- package/dist/knowledge/skills/views-add-composite-view/SKILL.md +5 -1
- package/dist/knowledge/skills/views-add-custom-view/SKILL.md +1 -0
- package/dist/knowledge/skills/views-app-level/SKILL.md +2 -1
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +43 -1
- package/dist/knowledge/skills/views-chart-authoring/references/framework-resource-chart-data-api.md +102 -0
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -1
- package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +3 -2
- package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -0
- package/dist/knowledge/skills/website-anonymous-session/SKILL.md +29 -6
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +3 -2
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +17 -4
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +23 -28
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +7 -22
- package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +167 -20
- package/dist/knowledge/skills/website-factory-advanced/SKILL.md +4 -3
- package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +63 -6
- package/dist/knowledge/skills/website-inbound-contact-forms/references/framework-submission-challenge-api.md +275 -0
- package/dist/knowledge/skills/website-label-pack/SKILL.md +13 -5
- package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -2
- package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +11 -2
- package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/website-page-authoring/SKILL.md +117 -33
- package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +164 -0
- package/dist/knowledge/skills/website-page-variants/SKILL.md +1 -0
- package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +1 -0
- package/dist/knowledge/skills/website-section-contact/SKILL.md +65 -36
- package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-cta/SKILL.md +32 -22
- package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-faq/SKILL.md +99 -63
- package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +27 -18
- package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +33 -22
- package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +31 -20
- package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-hero/SKILL.md +65 -44
- package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +217 -200
- package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +248 -0
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +45 -34
- package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +19 -11
- package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +8 -3
- package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +64 -34
- package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +30 -25
- package/dist/knowledge/skills/worker-authoring/SKILL.md +1 -0
- package/dist/knowledge/topic-index.json +5887 -1695
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +4 -4
- package/dist/knowledge/skills/journey-approve/SKILL.md +0 -63
- package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +0 -77
- package/dist/knowledge/skills/journey-next/SKILL.md +0 -82
- package/dist/knowledge/skills/journey-report/SKILL.md +0 -56
- package/dist/knowledge/skills/journey-run/SKILL.md +0 -140
- package/dist/knowledge/skills/journey-status/SKILL.md +0 -60
- /package/dist/{knowledge/skills/journey-approve → claude-marketplace/plugins/wildo}/references/specification-family-map.md +0 -0
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: resource-external-data
|
|
3
|
-
description: Bring data that lives in another system — an enterprise Odoo, an SAP OData service, a REST API — into the application, either as a read-through virtual resource or as a synced pipeline into an ordinary local resource. Use when the user says "read our customers from Odoo", "sync suppliers from SAP", "connect to our ERP", "pull data from an external API", "mirror the CRM contacts", "our products live in another system", "show data we do not own", "keep a local copy of the supplier list", or asks whether an integration should copy data or read it live.
|
|
3
|
+
description: Bring data that lives in another system — an enterprise Odoo, an SAP OData service, a REST API — into the application, either as a read-through virtual resource or as a synced pipeline into an ordinary local resource. Use when the user says "read our customers from Odoo", "sync suppliers from SAP", "connect to our ERP", "pull data from an external API", "mirror the CRM contacts", "our products live in another system", "show data we do not own", "keep a local copy of the supplier list", or asks whether an integration should copy data or read it live. Also when a row must be created, updated or deleted in that system from the application ("create the partner in Odoo", "write back to our ERP"), or when records the application creates must be sent to it ("send our new leads to Odoo", "push the requests we capture into the ERP").
|
|
4
|
+
user-invocable: false
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# External Data — Workflow
|
|
@@ -55,8 +56,10 @@ run.
|
|
|
55
56
|
|
|
56
57
|
- **The application owns the data** — that is an ordinary resource; use `resource-add-resource`.
|
|
57
58
|
- **You are adding a provider or credential**, not consuming data — that is provider configuration.
|
|
58
|
-
- **
|
|
59
|
-
|
|
59
|
+
- **The same rows must be edited on BOTH sides.** A pipeline runs one direction: INBOUND copies the
|
|
60
|
+
system of record's rows in, OUTBOUND sends the application's own rows out (see "When the application
|
|
61
|
+
is the source" below). A row changed on both sides needs a conflict policy, which is not built — say
|
|
62
|
+
so plainly rather than declaring two pipelines over one resource.
|
|
60
63
|
|
|
61
64
|
## Workflow
|
|
62
65
|
|
|
@@ -83,8 +86,10 @@ Both lanes name a `system`: an instance you declare under `systemsOfRecord` in
|
|
|
83
86
|
`wildo.saas.config.ts`. An instance is a deployment — *your* company's Odoo, *your* SAP tenant — and
|
|
84
87
|
it names a **vendor**.
|
|
85
88
|
|
|
86
|
-
The vendor is not a label. It selects a **facet**: the
|
|
87
|
-
is, as a system of record. The
|
|
89
|
+
The vendor is not a label. It selects a **facet**: the systems-of-record library's description of what
|
|
90
|
+
that vendor is, as a system of record. The library is `@wildo-ai/systems-of-record`, an opt-in package
|
|
91
|
+
`wildo config sync` adds to your backend once you declare an instance; run `pnpm install` after it
|
|
92
|
+
does. The facet decides four things you therefore do not:
|
|
88
93
|
|
|
89
94
|
| the facet says | so you do not |
|
|
90
95
|
|---|---|
|
|
@@ -99,7 +104,7 @@ be inventing a dialect and an auth scheme.
|
|
|
99
104
|
|
|
100
105
|
#### Choosing: a named vendor, or the generic `odata`
|
|
101
106
|
|
|
102
|
-
The
|
|
107
|
+
The library describes **seven** vendors — `odoo`, `microsoft-dataverse`,
|
|
103
108
|
`microsoft-dynamics-365-business-central`, `netsuite`, `salesforce`, `sap-s4hana`, and the generic
|
|
104
109
|
`odata`.
|
|
105
110
|
|
|
@@ -112,7 +117,7 @@ The catalogue describes **seven** vendors — `odoo`, `microsoft-dataverse`,
|
|
|
112
117
|
is the only one that parses: if the system is not OData v4, `odata` will fail at the first read,
|
|
113
118
|
further from the cause.
|
|
114
119
|
|
|
115
|
-
Two naming traps, both real: the Microsoft Web API
|
|
120
|
+
Two naming traps, both real: the Microsoft Web API is known under three provider
|
|
116
121
|
ids, and only **`microsoft-dataverse`** has a facet — `microsoft-dynamics-365` and
|
|
117
122
|
`microsoft-dynamics-crm` do not, and naming one is refused. And the SAP facet is **`sap-s4hana`**,
|
|
118
123
|
not `sap-s4hana-cloud`.
|
|
@@ -123,13 +128,20 @@ Read this BEFORE you meet it as a refusal, or you will file a bug against a limi
|
|
|
123
128
|
|
|
124
129
|
- **`sap-s4hana` — HTTP Basic only.** Its communication user prefers an X.509 client certificate,
|
|
125
130
|
which is a TRANSPORT credential the outbound seam has no channel for yet.
|
|
126
|
-
- **`sap-s4hana` — OData v4
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
131
|
+
- **`sap-s4hana` — OData v4 AND v2, one instance per service root.** SAP's most-used API
|
|
132
|
+
(`API_BUSINESS_PARTNER`, `/sap/opu/odata/sap/…`) is **v2**; declare `dialect: ODATA_V2` on the instance
|
|
133
|
+
AND the binding for it, and `ODATA` for a v4 root (`/sap/opu/odata4/…`). A system reached over both is
|
|
134
|
+
two instances, each with its own `maxRequestsPerMinute` — their SUM must fit the vendor's allowance. A
|
|
135
|
+
v2 root declared as `ODATA` is refused at the first read, naming the dialect to declare. A v2 source
|
|
136
|
+
READS only. See `references/odata-v2-sources.md`.
|
|
137
|
+
- **`salesforce`, `netsuite` — unsorted, and a pipeline needs a keyset.** Both are REST_JSON, which
|
|
138
|
+
declares no sort translation, so a `sortFields` declaration on them is refused at registration. They
|
|
139
|
+
feed a pipeline only when the binding's `list` statement declares a `keyset` — offset paging is
|
|
140
|
+
refused for pipelines. See `references/rest-keyset-sources.md`. A DATE filter on them needs the
|
|
141
|
+
column's kind declared — `fieldMappings: [{ localField, remoteField, temporalKind: HttpApiRemoteTemporalKind.DATE }]`
|
|
142
|
+
(or `DATE_TIME`) —
|
|
143
|
+
because SOQL and SuiteQL spell a date and a date-time differently and never as a quoted string; an
|
|
144
|
+
undeclared one is refused.
|
|
133
145
|
- **`microsoft-dataverse`, `salesforce` — cursor-paged.** Page N costs N requests, because a
|
|
134
146
|
continuation cursor has no page number. The engine refuses past twenty pages rather than walking
|
|
135
147
|
indefinitely. A caller that deep wants a filter.
|
|
@@ -153,10 +165,45 @@ them:
|
|
|
153
165
|
organization that owns the application, so the engine's per-row gate decides — nothing about your
|
|
154
166
|
tenants is pushed to a remote that has never heard of them.
|
|
155
167
|
- **`erasure`** — what happens to this data when a person asks to be erased. Every stance is a real
|
|
156
|
-
answer, including "this holds no personal data"; there is no silent option.
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
168
|
+
answer, including "this holds no personal data"; there is no silent option. That answer must agree
|
|
169
|
+
with your fields: `NO_SUBJECT_DATA` is refused at startup when any field that comes from the system
|
|
170
|
+
declares `.dataCategories()` (every field of a read-through resource; the mapped fields of a
|
|
171
|
+
pipeline). Settle it by fact — a company's name and contact details are data about a legal person,
|
|
172
|
+
not personal data, so they carry no category; a person's name does, and needs a stance that can
|
|
173
|
+
erase it or acknowledges it cannot.
|
|
174
|
+
|
|
175
|
+
One declaration is optional and belongs beside `erasure` whenever the rows hold personal data:
|
|
176
|
+
**`purposeRefs`**, the `purposeRef`s of `operatorComplianceIdentity.lawfulBases` this data is read for.
|
|
177
|
+
See "Which purpose the data serves" below.
|
|
178
|
+
|
|
179
|
+
**Writing rows back** — creating, updating or deleting ONE row of the remote system — is opened by
|
|
180
|
+
`writableVerbs` on the binding and performed by ordinary `CREATE` / `UPDATE` / `DELETE` operations.
|
|
181
|
+
Read `references/read-through-writes.md` before you open one: it owns the whole contract, and four
|
|
182
|
+
parts of it are not guessable —
|
|
183
|
+
|
|
184
|
+
- the write lands in the OWNER organization's system only, and in the caller's unit's partition;
|
|
185
|
+
- every write variant REQUIRES an `Idempotency-Key` (the framework sets it), and a timeout answers
|
|
186
|
+
`SYSTEM_OF_RECORD_WRITE_OUTCOME_UNKNOWN`, which a client must not answer by resending;
|
|
187
|
+
- no bulk write, no nested child writes, no queued write, no write inside a transaction;
|
|
188
|
+
- whether your dialect can write at all is the engine's — a binding opening a verb its dialect cannot
|
|
189
|
+
send is refused at startup, naming the dialect. Odoo (`ODOO_JSONRPC`), OData v4 (`ODATA`) and
|
|
190
|
+
REST_JSON write; OData v2 (`ODATA_V2`) reads only, and SAP S/4HANA does not write (its CSRF-token
|
|
191
|
+
handshake is not performed). A REST_JSON
|
|
192
|
+
binding DECLARES each write it opens — `operations.create` / `update` / `delete`, a method and a
|
|
193
|
+
path, and for a create where the vendor answers the new key (the body, or `Location`);
|
|
194
|
+
- a binding opening `update` must state `writeConcurrency`: `VERSION_CHECKED` on a
|
|
195
|
+
field mapped to the vendor's row version, or `LAST_WRITER_WINS`. On Odoo (`write_date`) the check is
|
|
196
|
+
BEST-EFFORT — it narrows the race and never closes it. On OData (`@odata.etag`) the version travels
|
|
197
|
+
as `If-Match` and the service itself refuses a stale write (412, `…_WRITE_PRECONDITION_FAILED`).
|
|
198
|
+
|
|
199
|
+
**Running an ERP action** — posting an invoice, confirming an order, an OData action — is not a row
|
|
200
|
+
write. Declare it on the binding under `actions`, expose it through one custom operation of the
|
|
201
|
+
resource that calls `utils.systemOfRecordActions.run(...)` — NAMED as its door in
|
|
202
|
+
`actions.<name>.operation` and borrowing `UPDATE` (a keyed `PUT`), which is what exempts it from
|
|
203
|
+
`writableVerbs` — and read `references/system-of-record-actions.md`:
|
|
204
|
+
it runs only in the system-of-record lane (never as a provider operation), for the owner organization,
|
|
205
|
+
by the action's declared roles, on a record read first through this resource's gates, with an
|
|
206
|
+
Idempotency-Key when it writes, and every attempt is audited.
|
|
160
207
|
|
|
161
208
|
### Step 3B — Pipeline: declare `externalDataPipeline` on an ORDINARY local resource
|
|
162
209
|
|
|
@@ -167,9 +214,11 @@ rows come from. Read `references/framework-external-data-pipeline-api.md` for th
|
|
|
167
214
|
The four decisions that matter:
|
|
168
215
|
|
|
169
216
|
1. **`remoteKeyLocalField`** — a `.isBusinessKey()` STRING field holding the remote row's identity.
|
|
170
|
-
The sync merges on it, which is what makes re-running safe.
|
|
171
|
-
|
|
172
|
-
|
|
217
|
+
The sync merges on it, which is what makes re-running safe. (An OUTBOUND pipeline reverses this and
|
|
218
|
+
the next rule — see "When the application is the source".)
|
|
219
|
+
2. **`mapping`** — remote field → local field, plus constants for local fields with no remote source,
|
|
220
|
+
and DECLARED EXPRESSIONS for a value derived from remote fields (see "When a local value is derived"
|
|
221
|
+
below). It must NOT name your tenant field; see the next section.
|
|
173
222
|
3. **`population`** — `CLOSED` (every row comes from the pipeline; caller CREATE is refused) or
|
|
174
223
|
`OPEN` (users may also mint their own rows beside the synced ones).
|
|
175
224
|
4. **`orphanPolicy`** — what happens to a local row whose remote original disappeared: `DELETE`,
|
|
@@ -231,6 +280,22 @@ pipeline instead of manually advancing its cursor.
|
|
|
231
280
|
|
|
232
281
|
Run the verification greps below, then check that a sync produced the rows you expect.
|
|
233
282
|
|
|
283
|
+
### When a pipeline misbehaves: where to look
|
|
284
|
+
|
|
285
|
+
Every run leaves a history row, so start from the pipeline's history, not the logs. From the
|
|
286
|
+
application root, `wildo context pipelines` lists every declared pipeline with its health, and
|
|
287
|
+
`wildo context pipelines --runs <resourceType>` prints one pipeline's runs; both read the admin door
|
|
288
|
+
(`references/framework-pipeline-admin-endpoints-api.md`), which answers each question below.
|
|
289
|
+
|
|
290
|
+
| Symptom | Read |
|
|
291
|
+
|---|---|
|
|
292
|
+
| Is it running at all, and is the copy current? | the listing's `health`: `lastRunAt`, `lastCompletedPassAt`, `lastCompletedFullPassAt` |
|
|
293
|
+
| It keeps failing | `health.consecutiveFailures`, then `GET …/runs`: each failed run's `failureKind` and `failureMessage` |
|
|
294
|
+
| The source is down | the listing's `sourceUnreachable` streak; scheduled runs back off on their own |
|
|
295
|
+
| Some source rows never arrive | `GET …/runs`: the run's `rejections` (remote key and reason), then fix the data at the source |
|
|
296
|
+
| A run refuses its stored state on every tick | `POST …/reset` with `restart-pass` |
|
|
297
|
+
| Rows loaded but look wrong | the run's `seedRunId`, then that load ledger's per-entry outcomes |
|
|
298
|
+
|
|
234
299
|
## When the instance is PARTITIONED
|
|
235
300
|
|
|
236
301
|
Some systems of record hold several partitions inside one corporate — Odoo
|
|
@@ -245,6 +310,13 @@ codec, whether the value arrives as a many2one pair — comes from the vendor, n
|
|
|
245
310
|
from you; the instance only opts in, and boot refuses if the vendor partitions by
|
|
246
311
|
something that cannot be confined.
|
|
247
312
|
|
|
313
|
+
**When the vendor's facet declares no partition but a package does**, the package ships a facet
|
|
314
|
+
AUGMENTATION and the instance opts into it with `facetAugmentations: ['<package>']`. Nothing is applied
|
|
315
|
+
because a package is installed, and a partition declared twice is refused at boot, naming both sources.
|
|
316
|
+
A package discovery does not walk by name (another scope's, or yours not named `provider-*`) must also be
|
|
317
|
+
listed in `providers.packages`, and your backend package
|
|
318
|
+
must depend on it. Only a FIELD partition can be confined. Read `references/facet-augmentations.md`.
|
|
319
|
+
|
|
248
320
|
**Who maps a partition to a unit is an operator**, through
|
|
249
321
|
`systemOfRecordPartitionAssignments`. See the `authorization-unit-narrowing`
|
|
250
322
|
skill for that door and for what it means to a caller.
|
|
@@ -291,6 +363,146 @@ un-assignment reversible.
|
|
|
291
363
|
A row whose partition field is unset is **shared**: visible to every caller,
|
|
292
364
|
carrying no unit, and both stamps land null on it.
|
|
293
365
|
|
|
366
|
+
## When the source is large: read only what changed (`incremental`)
|
|
367
|
+
|
|
368
|
+
A pipeline with no `incremental` re-reads its whole source on every pass. For a large Odoo model that
|
|
369
|
+
is hundreds of runs per pass. Declare `incremental` and the pipeline runs TWO independent tracks:
|
|
370
|
+
|
|
371
|
+
- **incremental passes** on `scheduleCron` read only rows changed since a watermark — Odoo's own
|
|
372
|
+
own `write_date` position of the last rows loaded, never your clock — and NEVER delete;
|
|
373
|
+
- **full passes** on `incremental.fullPassCron` read everything and are the only thing that can find a
|
|
374
|
+
row deleted in the source. That is why the cadence is required.
|
|
375
|
+
|
|
376
|
+
The two never block each other, and a row an incremental pass loads while a long full pass is in
|
|
377
|
+
flight is never mistaken for a deletion when that full pass completes. A change to what is extracted
|
|
378
|
+
or how it is loaded (mapping, keys, `sourceFilter`, partition assignments, …) drops the watermark, so
|
|
379
|
+
the next incremental pass reads the whole source once. Refused at startup: a mode the source's
|
|
380
|
+
dialect or vendor does not support, and `incremental` without `scheduleCron`. Three modes exist: Odoo's
|
|
381
|
+
`write_date`, and for an OData v4 source a modified-at filter or the delta-link protocol (which also reads
|
|
382
|
+
DELETIONS); OData v2 and REST sources run full passes.
|
|
383
|
+
|
|
384
|
+
Read `references/incremental-extraction.md` before declaring it: the lookback, what re-reads the
|
|
385
|
+
source, and how to read a run.
|
|
386
|
+
|
|
387
|
+
## Rate budgets: two per call, and only a pipeline waits
|
|
388
|
+
|
|
389
|
+
Every remote call spends TWO local budgets and is sent only if both have room. The instance budget and a
|
|
390
|
+
virtual resource's ceiling are counted in the application's Redis, once for every backend replica (a process
|
|
391
|
+
with no Redis counts on its own); a pipeline's ceiling stays in the process holding its lease:
|
|
392
|
+
|
|
393
|
+
- the **instance** budget, `systemsOfRecord.<name>.maxRequestsPerMinute` — one allowance shared by every
|
|
394
|
+
virtual resource and pipeline bound to that instance, because the vendor counts them as one caller;
|
|
395
|
+
- the **binding** ceiling, `remoteCallSemantics.maxRequestsPerMinute` — how much of that allowance ONE
|
|
396
|
+
resource or pipeline may take.
|
|
397
|
+
|
|
398
|
+
A **read-through call** (a person listing rows) refuses at once when either is full: someone is waiting,
|
|
399
|
+
and a wait they cannot see is worse than an error they can. A **pipeline run PACES**: it waits for its
|
|
400
|
+
binding ceiling to have room, backs off briefly when only the instance is full, and waits as long as a
|
|
401
|
+
throttling source's `Retry-After` asks. `maxRunDurationMs` (default 15 minutes) bounds the waiting; when
|
|
402
|
+
it comes, the run stops as a PARTIAL pass — every page it loaded is kept (a run loads each page before it
|
|
403
|
+
reads the next), the cursor continues the pass on the next run — never as a failure. The run report and the stored last-run summary carry `pacing`: the time
|
|
404
|
+
spent waiting, how many waits, and whether the run stopped at its deadline.
|
|
405
|
+
|
|
406
|
+
So when the instance declares a budget, the pipeline's binding ceiling must be **strictly below** it —
|
|
407
|
+
the difference is what a person's read keeps while a pass runs. Startup refuses an absent or equal
|
|
408
|
+
ceiling, naming both values. Read `references/rate-budgets-and-pacing.md` to choose the numbers.
|
|
409
|
+
|
|
410
|
+
## When the source is Odoo: ARCHIVED records are not deleted records
|
|
411
|
+
|
|
412
|
+
Odoo archives a record by setting its `active` field to `false`, and hides archived records from
|
|
413
|
+
every search by default. A pipeline cannot inherit that default: its orphan comparison reads "absent
|
|
414
|
+
from a complete pass" as "deleted in the source", so a hidden archived record would be deleted,
|
|
415
|
+
deprecated or reported as gone by your `orphanPolicy`, taking its local fields, files and retrieval
|
|
416
|
+
chunks with it.
|
|
417
|
+
|
|
418
|
+
So an Odoo pipeline **always extracts archived records too**, and an archived record is **always
|
|
419
|
+
counted as present**. No setting can turn archiving into deletion. What you choose is only whether an
|
|
420
|
+
archived record is LOADED, with `archivedRecords`:
|
|
421
|
+
|
|
422
|
+
| `archivedRecords` | an archived record is | choose it when |
|
|
423
|
+
|---|---|---|
|
|
424
|
+
| absent, or `{ treatment: 'load' }` (the default) | loaded like any other row | the destination should show archival. Map Odoo's `active` onto a local boolean like any other field; an un-archive then changes exactly that one value |
|
|
425
|
+
| `{ treatment: 'exclude-from-load' }` | not loaded, still counted as present | archived records should never enter the destination. A row loaded while the record was live KEEPS its last loaded version until the record is un-archived. `archiveFlagRemoteField` defaults to `active`; name `x_active` for a Studio model |
|
|
426
|
+
|
|
427
|
+
Under `exclude-from-load`, a row whose archive flag is missing or not a boolean is REJECTED with that
|
|
428
|
+
reason (and still counted as present), because excluding or loading on a guess would both be wrong.
|
|
429
|
+
The run reports `excludedArchivedRows`, and the persisted last-run summary keeps it.
|
|
430
|
+
|
|
431
|
+
`archivedRecords` is refused on an OData source: OData has no protocol-level archive state. The
|
|
432
|
+
read-through lane keeps Odoo's default — a person listing partners does not see archived ones, as in
|
|
433
|
+
Odoo's own list views — while a subject erasure searches archived records too.
|
|
434
|
+
|
|
435
|
+
## When a copied person is erased: the suppression list
|
|
436
|
+
|
|
437
|
+
Nothing to declare. An erasure that scrubs or deletes a pipeline-copied row records a SUPPRESSION of its
|
|
438
|
+
remote record — a keyed hash, never the key — and every later pass, full or incremental, loads nothing
|
|
439
|
+
under it and counts the skip as `suppressedRows`. It is released only by a completed full pass over the
|
|
440
|
+
whole remote entity (no `sourceFilter`) that no longer sees the record. Read
|
|
441
|
+
`references/erasure-suppression.md`, including the one refusal: a changed `encryptionKey` stops runs.
|
|
442
|
+
|
|
443
|
+
## Which purpose the data serves: `purposeRefs`
|
|
444
|
+
|
|
445
|
+
Personal data read or copied from a system of record was not collected from the person, so the
|
|
446
|
+
application's privacy notice owes where it came from, which categories, and the purpose and legal basis
|
|
447
|
+
for obtaining it (GDPR Art. 14). The source and the categories are derived: the `system` you bind and the
|
|
448
|
+
`.dataCategories()` on your fields. The purpose is the one thing only you know, so declare it on the
|
|
449
|
+
binding — `httpApiBinding.purposeRefs`, or `externalDataPipeline.binding.purposeRefs` for a copy — naming
|
|
450
|
+
entries of `operatorComplianceIdentity.lawfulBases` in `wildo.saas.config.ts`:
|
|
451
|
+
|
|
452
|
+
- nothing refuses at startup without it; the source statement in the notice then marks its purpose as owed;
|
|
453
|
+
- a ref naming no declared purpose is reported (the computed fact lists it under
|
|
454
|
+
`purposeRefsNamingNoPurpose`), never silently dropped;
|
|
455
|
+
- a pipeline copy also needs a retention class on its destination resource, or the notice says the copy is
|
|
456
|
+
kept until erased.
|
|
457
|
+
|
|
458
|
+
The notice also owes whether the data can have come from publicly accessible sources. That is a property of
|
|
459
|
+
the INSTANCE — how records got into your ERP — so state it once on the instance:
|
|
460
|
+
`systemsOfRecord.<name>.personalDataOrigin`, `SystemOfRecordPersonalDataOrigin.NO_PUBLICLY_ACCESSIBLE_SOURCES`
|
|
461
|
+
or `INCLUDES_PUBLICLY_ACCESSIBLE_SOURCES` (from `@wildo-ai/saas-models`). Omitted, the notice marks that
|
|
462
|
+
statement owed for every resource read from the instance; it is never read as "no".
|
|
463
|
+
|
|
464
|
+
The `compliance-document-authoring` skill turns these into the notice's source statement.
|
|
465
|
+
|
|
466
|
+
## When a remote record REFERENCES another one: `REMOTE_REFERENCE`
|
|
467
|
+
|
|
468
|
+
An Odoo `res.partner.parent_id` or an OData navigation key should not land as a bare remote id: map it
|
|
469
|
+
with a `REMOTE_REFERENCE` entry onto a declared relationship foreign key, and the pipeline writes the
|
|
470
|
+
LOCAL id of the target's copy. The foreign key is written after the load, in its own phase, so a child
|
|
471
|
+
extracted before its parent — and a self-reference — link without ordering anything. A target with no
|
|
472
|
+
local row yet leaves the key empty and PENDING, retried at the end of every later run, incremental ones
|
|
473
|
+
included; `pendingReferences` on the run report says how many wait. The target must be a pipeline
|
|
474
|
+
destination or a virtual resource on the SAME system of record. Read `references/remote-references.md`,
|
|
475
|
+
including the orphan-cascade refusal.
|
|
476
|
+
|
|
477
|
+
## When a local value is DERIVED from remote fields: declared expressions
|
|
478
|
+
|
|
479
|
+
A vendor code that must become one of your enum's members, a display name built from two fields, an
|
|
480
|
+
amount at a declared rate, a value chosen by a flag: declare an `ENUM_MAP`, `CONCATENATION`,
|
|
481
|
+
`ARITHMETIC` or `CONDITIONAL` mapping entry. They are data, checked against your destination schema at
|
|
482
|
+
startup, and every remote field they read is requested by the extraction. There is no transform
|
|
483
|
+
function — an unknown key on a mapping entry is refused. A code the declaration does not map rejects
|
|
484
|
+
the row and the run reports it. Read `references/declared-expressions.md`.
|
|
485
|
+
|
|
486
|
+
## What a reader sees on a synced field: the provenance note
|
|
487
|
+
|
|
488
|
+
On a read surface, every field the pipeline writes carries a note beneath its value — "Synced from Odoo ·
|
|
489
|
+
as of 12 minutes ago" — and your own columns carry none. It needs a READ view for the destination and the
|
|
490
|
+
generated instance label `systems_of_record.<name>.displayName`; you never author the words. Read
|
|
491
|
+
`references/provenance-cue.md`.
|
|
492
|
+
|
|
493
|
+
## When the application is the source: `direction: OUTBOUND`
|
|
494
|
+
|
|
495
|
+
When a record is BORN in the application and the system of record must also have it — leads captured
|
|
496
|
+
here that belong in Odoo — declare the pipeline with `direction: ExternalDataPipelineDirection.OUTBOUND`
|
|
497
|
+
on the destination your users write. Every save records a change; each pass sends the row as it stands
|
|
498
|
+
now: a CREATE the first time (its answered key is written to `remoteKeyLocalField`), an UPDATE after.
|
|
499
|
+
The ownership rules reverse: the mapped fields are the application's and stay writable, the remote key is
|
|
500
|
+
an optional engine-written string. Only the owner organization's rows are ever sent, a local delete never
|
|
501
|
+
is, and an unknown-outcome CREATE waits for an operator rather than risk a duplicate. It needs
|
|
502
|
+
`writableVerbs` including `CREATE`, `LAST_WRITER_WINS`, `REMOTE_FIELD`/`REMOTE_REFERENCE` entries only, and
|
|
503
|
+
— until erasure reaches sent records — `NO_SUBJECT_DATA` with no personal-data field. Read
|
|
504
|
+
`references/outbound-pipelines.md`.
|
|
505
|
+
|
|
294
506
|
## Worked Example
|
|
295
507
|
|
|
296
508
|
## Import Origins
|
|
@@ -303,9 +515,53 @@ carrying no unit, and both stamps land null on it.
|
|
|
303
515
|
|
|
304
516
|
```typescript
|
|
305
517
|
export enum ExternalDataPipelineDirection {
|
|
518
|
+
/**
|
|
519
|
+
* The system of record is the source: a pass reads its rows and loads them into the destination. The mapped fields
|
|
520
|
+
* are remote-authoritative, so callers may not write them.
|
|
521
|
+
*/
|
|
306
522
|
INBOUND = 'inbound',
|
|
523
|
+
/**
|
|
524
|
+
* The destination is the source (#1690): a row created or changed locally is sent to the system of record on the
|
|
525
|
+
* next pass — created there when it has no remote key yet, updated when it has one. The mapped fields are the
|
|
526
|
+
* application's own, so callers write them; the remote key is written by the engine, once, from the create's answer.
|
|
527
|
+
*
|
|
528
|
+
* Only rows of the organization that owns the application are ever sent (a system of record belongs to it alone),
|
|
529
|
+
* and on a partitioned instance only rows whose organization unit is assigned to a partition. A local DELETE is not
|
|
530
|
+
* sent: a system of record keeps its own records, and removing one is its operator's decision, not a side effect of
|
|
531
|
+
* a local edit.
|
|
532
|
+
*/
|
|
533
|
+
OUTBOUND = 'outbound',
|
|
534
|
+
/**
|
|
535
|
+
* Both sides change the row (#1723): a pass LOADS what the system of record changed and SENDS what the application
|
|
536
|
+
* changed, field by field, as each mapping entry's `owner` declares — REMOTE fields are loaded and read-only locally,
|
|
537
|
+
* LOCAL fields are sent and never loaded, BOTH fields are loaded AND sent. A row whose BOTH fields changed on both
|
|
538
|
+
* sides since they last agreed is a CONFLICT, decided by the declared `conflictPolicy`.
|
|
539
|
+
*
|
|
540
|
+
* "Since they last agreed" is the system of record's own row version (Odoo `write_date`, an OData entity tag), kept
|
|
541
|
+
* per row by the engine — so the direction is legal only on an instance whose vendor declares one. A local DELETE is
|
|
542
|
+
* not sent, as on OUTBOUND.
|
|
543
|
+
*/
|
|
544
|
+
BIDIRECTIONAL = 'bidirectional',
|
|
307
545
|
}
|
|
308
546
|
|
|
547
|
+
/**
|
|
548
|
+
* Which side OWNS a mapped field of a BIDIRECTIONAL pipeline (#1723). Declared on each `REMOTE_FIELD` / `REMOTE_REFERENCE`
|
|
549
|
+
* entry as `owner`, and refused on any other direction (an INBOUND pipeline's fields are all the system of record's, an
|
|
550
|
+
* OUTBOUND pipeline's all the application's).
|
|
551
|
+
*
|
|
552
|
+
* Only BOTH fields can conflict, which keeps the common case — remote master data plus a few locally-owned fields —
|
|
553
|
+
* out of conflict handling entirely.
|
|
554
|
+
*/
|
|
555
|
+
export enum ExternalDataFieldOwner {
|
|
556
|
+
/** The system of record's: loaded, read-only for callers, never sent. The default when `owner` is omitted. */
|
|
557
|
+
REMOTE = 'remote',
|
|
558
|
+
/** The application's: written by callers, sent, never loaded. */
|
|
559
|
+
LOCAL = 'local',
|
|
560
|
+
/** Both sides': written by callers AND loaded, sent AND read back — the only kind of field that can conflict. */
|
|
561
|
+
BOTH = 'both',
|
|
562
|
+
}
|
|
563
|
+
|
|
564
|
+
|
|
309
565
|
/**
|
|
310
566
|
* Who owns the destination's row population (D-P8, v3.1 §1).
|
|
311
567
|
*
|
|
@@ -348,18 +604,164 @@ export enum ExternalDataOrphanPolicy {
|
|
|
348
604
|
REPORT = 'report',
|
|
349
605
|
}
|
|
350
606
|
|
|
351
|
-
/**
|
|
607
|
+
/**
|
|
608
|
+
* The shapes a mapping entry can take — a closed discriminator, never inferred from keys.
|
|
609
|
+
*
|
|
610
|
+
* ## The DECLARED EXPRESSIONS (#1685), and the open function slot they replace
|
|
611
|
+
*
|
|
612
|
+
* `ENUM_MAP`, `CONCATENATION`, `ARITHMETIC` and `CONDITIONAL` derive a local value from remote values. They are
|
|
613
|
+
* the first of the T's recorded widenings (D-P4: computed transforms, then multi-source joins, then transforms
|
|
614
|
+
* authored by the app-creation lane's agents) and they are DATA: every one names the remote fields it reads, the
|
|
615
|
+
* local field it writes, and a closed operation with declared constants. Nothing in them executes code the
|
|
616
|
+
* declaration does not show, so each is checked at startup against the destination schema (target type, enum
|
|
617
|
+
* membership, absence) and requested by the extraction like any mapped field.
|
|
618
|
+
*
|
|
619
|
+
* An open function slot (`transform: (row) => value`) is refused on purpose: it would put arbitrary code inside the
|
|
620
|
+
* load with no declaration anyone can review, validate or fingerprint. A derivation beyond these four stays a
|
|
621
|
+
* pre-load step in the application's own code, run by its own job.
|
|
622
|
+
*/
|
|
352
623
|
export enum ExternalDataMappingEntryKind {
|
|
353
624
|
/** Copy (and coerce) one remote field into one local field. */
|
|
354
625
|
REMOTE_FIELD = 'remote-field',
|
|
355
626
|
/** Fill one local field with a declared constant (destination-required fields with no remote source). */
|
|
356
627
|
CONSTANT = 'constant',
|
|
628
|
+
/**
|
|
629
|
+
* Turn a remote REFERENCE into a real local foreign key (#1684) — an Odoo many2one (`parent_id`,
|
|
630
|
+
* `partner_id`), an OData navigation key. The remote value names a row of ANOTHER remote entity (or of
|
|
631
|
+
* the same one); the pipeline writes the local foreign key to that row's LOCAL copy, never the remote
|
|
632
|
+
* id. See {@link ExternalDataRemoteReferenceMappingEntrySchema}.
|
|
633
|
+
*/
|
|
634
|
+
REMOTE_REFERENCE = 'remote-reference',
|
|
635
|
+
/**
|
|
636
|
+
* Map a remote CODE onto a member of a local enum (#1685) — an Odoo selection (`draft`/`posted`), a vendor status
|
|
637
|
+
* code. Every mapped code is declared; a code the declaration does not name either rejects the row or lands a
|
|
638
|
+
* declared default. See {@link ExternalDataEnumMappingEntrySchema}.
|
|
639
|
+
*/
|
|
640
|
+
ENUM_MAP = 'enum-map',
|
|
641
|
+
/**
|
|
642
|
+
* Join remote fields and literals into one local string (#1685) — a display name from a first and a last name.
|
|
643
|
+
* See {@link ExternalDataConcatenationMappingEntrySchema}.
|
|
644
|
+
*/
|
|
645
|
+
CONCATENATION = 'concatenation',
|
|
646
|
+
/**
|
|
647
|
+
* `remote × factor + offset` on one numeric remote field (#1685) — a unit conversion, or a currency conversion at
|
|
648
|
+
* a DECLARED constant rate. See {@link ExternalDataArithmeticMappingEntrySchema}.
|
|
649
|
+
*/
|
|
650
|
+
ARITHMETIC = 'arithmetic',
|
|
651
|
+
/**
|
|
652
|
+
* Choose the local value by ONE remote field's value (#1685): a list of cases, each an exact value, and an
|
|
653
|
+
* `otherwise`. See {@link ExternalDataConditionalMappingEntrySchema}.
|
|
654
|
+
*/
|
|
655
|
+
CONDITIONAL = 'conditional',
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
/**
|
|
659
|
+
* The mapping entry kinds an OUTBOUND pipeline may declare (#1690): a local field sent as one remote field, and a local
|
|
660
|
+
* foreign key sent as the target row's REMOTE key. The declared expressions (#1685) derive one local value from remote
|
|
661
|
+
* ones and have no inverse — a concatenation cannot be split back into its parts — and a CONSTANT names no remote field.
|
|
662
|
+
*/
|
|
663
|
+
export const EXTERNAL_DATA_OUTBOUND_MAPPING_ENTRY_KINDS: ReadonlySet<ExternalDataMappingEntryKind> = new Set([
|
|
664
|
+
ExternalDataMappingEntryKind.REMOTE_FIELD,
|
|
665
|
+
ExternalDataMappingEntryKind.REMOTE_REFERENCE,
|
|
666
|
+
]);
|
|
667
|
+
|
|
668
|
+
/**
|
|
669
|
+
* The write verbs an OUTBOUND pipeline may open on its binding (#1690): a create for a row with no remote key yet, and
|
|
670
|
+
* an update for one that has one. DELETE is not among them — see {@link ExternalDataPipelineDirection.OUTBOUND}.
|
|
671
|
+
*/
|
|
672
|
+
export const EXTERNAL_DATA_OUTBOUND_WRITE_VERBS: ReadonlySet<HttpApiWriteVerb> = new Set([HttpApiWriteVerb.CREATE, HttpApiWriteVerb.UPDATE]);
|
|
673
|
+
|
|
674
|
+
/**
|
|
675
|
+
* What an `ENUM_MAP` does with a remote code its declaration does not name (#1685).
|
|
676
|
+
*/
|
|
677
|
+
export enum ExternalDataUnmappedValuePolicy {
|
|
678
|
+
/**
|
|
679
|
+
* The DEFAULT. The row is REJECTED and reported, and its previous local version survives. A vendor that adds a
|
|
680
|
+
* code is then visible on the next run's report instead of being folded silently into some other member.
|
|
681
|
+
*/
|
|
682
|
+
REJECT_ROW = 'reject-row',
|
|
683
|
+
/** The row lands the declared `localValue`. Choose it only where every future code genuinely means the same thing. */
|
|
684
|
+
USE_DEFAULT = 'use-default',
|
|
685
|
+
}
|
|
686
|
+
|
|
687
|
+
/** The two things a `CONCATENATION` part can be (#1685). */
|
|
688
|
+
export enum ExternalDataConcatenationPartKind {
|
|
689
|
+
/** The value of one remote field. An absent or empty value drops the part. */
|
|
690
|
+
REMOTE_FIELD = 'remote-field',
|
|
691
|
+
/** A declared literal, written as-is. */
|
|
692
|
+
LITERAL = 'literal',
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
/** The two things a `CONDITIONAL` outcome can be (#1685). */
|
|
696
|
+
export enum ExternalDataConditionalOutcomeKind {
|
|
697
|
+
/** A declared constant, checked against the local field's type at startup. */
|
|
698
|
+
CONSTANT = 'constant',
|
|
699
|
+
/** Another remote field's value, copied as a `REMOTE_FIELD` entry copies it. */
|
|
700
|
+
REMOTE_FIELD = 'remote-field',
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
/**
|
|
704
|
+
* How a REMOTE_REFERENCE's remote value becomes the target's key (#1684). A closed vocabulary, one
|
|
705
|
+
* member per wire shape, because the shapes differ in kind and guessing between them silently resolves
|
|
706
|
+
* nothing.
|
|
707
|
+
*/
|
|
708
|
+
export enum ExternalDataRemoteReferenceValueShape {
|
|
709
|
+
/**
|
|
710
|
+
* Odoo's many2one: `search_read` answers `[id, display_name]`, or `false` when the reference is empty.
|
|
711
|
+
* The key is the pair's FIRST element; the display name is ignored (it is a label, not an identity).
|
|
712
|
+
* spec-cite: Odoo 18.0 developer reference, External API — "Read records" / "Search and read"
|
|
713
|
+
* (`odoo/documentation/18.0/content/developer/reference/external_api.rst`) — a many2one reads as
|
|
714
|
+
* `[21, 'Belgium']`; `false` for an unset one is the ORM's null spelling (measured shape recorded on the
|
|
715
|
+
* provider simulator, `odoo-jsonrpc-mock.ts`).
|
|
716
|
+
*/
|
|
717
|
+
ODOO_MANY2ONE = 'odoo-many2one',
|
|
718
|
+
/**
|
|
719
|
+
* The remote value IS the target's key component, as a plain scalar — an OData navigation property's
|
|
720
|
+
* foreign-key field (`ParentAccountID`), a REST id column. `null` or an empty string is an empty reference.
|
|
721
|
+
*/
|
|
722
|
+
SCALAR = 'scalar',
|
|
723
|
+
}
|
|
724
|
+
|
|
725
|
+
/**
|
|
726
|
+
* What a run does with a reference whose target has no local row yet (#1684).
|
|
727
|
+
*
|
|
728
|
+
* Resolution happens AFTER the load, in its own phase, so a reference to a row loaded by the same run —
|
|
729
|
+
* including a child extracted before its parent, and a self-reference — always resolves. What remains
|
|
730
|
+
* "unresolved" is a target the destination does not hold at all: outside the pipeline's `sourceFilter`,
|
|
731
|
+
* in a partition nobody assigned, not yet loaded by the target's own pipeline.
|
|
732
|
+
*/
|
|
733
|
+
export enum ExternalDataUnresolvedReferencePolicy {
|
|
734
|
+
/**
|
|
735
|
+
* The DEFAULT. The row loads with the foreign key EMPTY, and the reference is kept in the pipeline's
|
|
736
|
+
* pending-resolution set. The set is retried at the end of EVERY later run of the pipeline, incremental
|
|
737
|
+
* ones included — which is the only way such a row is ever resolved under incremental extraction (#1682),
|
|
738
|
+
* because a child that did not change is never re-read. Counted on every run's report and summary.
|
|
739
|
+
*/
|
|
740
|
+
LEAVE_PENDING = 'leave-pending',
|
|
741
|
+
/**
|
|
742
|
+
* The row is REJECTED (reported per row; its previous local version survives) when its target is not
|
|
743
|
+
* already loaded and not among the rows of the same PAGE — a run loads page by page (#1689), so a target
|
|
744
|
+
* on a LATER page of the same run is not loaded yet. It is retried only when the row is extracted again
|
|
745
|
+
* — every full pass, or an incremental pass after it changes — and a pass that reads parents before their
|
|
746
|
+
* children never meets the case. For a self-referencing entity whose source order you do not control,
|
|
747
|
+
* `LEAVE_PENDING` resolves the link at the end of the same run instead. A reference to a VIRTUAL (read-through)
|
|
748
|
+
* target never rejects: its key is its local id, and there is nothing local to be missing.
|
|
749
|
+
*
|
|
750
|
+
* The check runs BEFORE the load, against the target as it stands then. A self-referenced target that the same
|
|
751
|
+
* full pass's orphan walk deletes (`orphanPolicy: DELETE`) saved the row from rejection and is then gone, so that
|
|
752
|
+
* row loads with its foreign key empty and pending — the one case this policy cannot rule out.
|
|
753
|
+
*/
|
|
754
|
+
REJECT_ROW = 'reject-row',
|
|
357
755
|
}
|
|
358
756
|
|
|
359
757
|
/**
|
|
360
758
|
* Built-in, closed coercion vocabulary for REMOTE_FIELD entries (v3.1 §3 / PR-8). Slice 1 ships
|
|
361
|
-
* exactly the coercions the two generic dialects force
|
|
362
|
-
*
|
|
759
|
+
* exactly the coercions the two generic dialects force. A value COMPUTED from remote fields is one of
|
|
760
|
+
* the declared expressions (#1685 — D-P4's first widening: `ENUM_MAP`, `CONCATENATION`, `ARITHMETIC`,
|
|
761
|
+
* `CONDITIONAL`), and transforms authored by the app-creation lane's agents remain a recorded widening
|
|
762
|
+
* (W-AGENT) — never an open function slot here. Foreign-key resolution,
|
|
763
|
+
* once recorded as the W-FK widening beside it, is not a coercion at all: it is its own entry kind,
|
|
764
|
+
* {@link ExternalDataMappingEntryKind.REMOTE_REFERENCE} (#1684).
|
|
363
765
|
*/
|
|
364
766
|
export enum ExternalDataFieldCoercion {
|
|
365
767
|
/** Value lands as extracted (after the destination schema's own Zod parse). */
|
|
@@ -374,9 +776,243 @@ export enum ExternalDataFieldCoercion {
|
|
|
374
776
|
ISO_STRING_TO_DATE = 'iso-string-to-date',
|
|
375
777
|
}
|
|
376
778
|
|
|
377
|
-
/**
|
|
779
|
+
/**
|
|
780
|
+
* What a pipeline does with a remote row its source has ARCHIVED rather than deleted (#1732).
|
|
781
|
+
*
|
|
782
|
+
* ## Why this exists: archived is not deleted, and absence reads as deletion
|
|
783
|
+
*
|
|
784
|
+
* Odoo archives a record by setting its `active` field to `false`, and an archived record is then
|
|
785
|
+
* "invisible in most searches and listing" — a plain `search_read` leaves it out, exactly as if it
|
|
786
|
+
* had been deleted.
|
|
787
|
+
* spec-cite: Odoo 17.0 ORM API reference, "Reserved Field names" → `Model.active`
|
|
788
|
+
* (https://www.odoo.com/documentation/17.0/developer/reference/backend/orm.html).
|
|
789
|
+
*
|
|
790
|
+
* A pipeline's orphan walk reads "absent from a complete pass" as "deleted remotely", so an extraction
|
|
791
|
+
* that inherited Odoo's default visibility turned every archive into a deletion: `REPORT` reported
|
|
792
|
+
* it, `DEPRECATE` deprecated it, and `DELETE` hard-deleted the local row together with its local
|
|
793
|
+
* extension fields, files and RAG chunks. Un-archiving later re-created a bare row.
|
|
794
|
+
*
|
|
795
|
+
* So extraction ALWAYS asks Odoo for archived rows too (the `active_test: false` context), and an
|
|
796
|
+
* archived row is always OBSERVED — present in the source, never an orphan. What remains a choice is
|
|
797
|
+
* only whether it is LOADED, and that is this vocabulary. Every member keeps the row observed; no
|
|
798
|
+
* member can turn an archive into a deletion.
|
|
799
|
+
*
|
|
800
|
+
* Declared on Odoo sources only (`archivedRecords`); an OData source has no protocol-level archive
|
|
801
|
+
* state, and the declaration coherence refuses the field there.
|
|
802
|
+
*/
|
|
803
|
+
export enum ExternalDataArchivedRecordTreatment {
|
|
804
|
+
/**
|
|
805
|
+
* The DEFAULT. An archived row is loaded like any other row. Map the source's archive flag
|
|
806
|
+
* (`active` on most Odoo models) onto a local boolean like any other field, and the destination can
|
|
807
|
+
* show or filter archived rows — and an un-archive changes exactly that one value.
|
|
808
|
+
*/
|
|
809
|
+
LOAD = 'load',
|
|
810
|
+
/**
|
|
811
|
+
* An archived row is NOT loaded, but still counts as observed, so it is never an orphan — the same
|
|
812
|
+
* treatment rows of an unassigned partition get. A local row loaded while the record was live KEEPS
|
|
813
|
+
* its last loaded version (it is neither updated nor deleted) until the record is un-archived.
|
|
814
|
+
* Choose it to keep archived records out of a destination that never held them; choose `LOAD` with
|
|
815
|
+
* the flag mapped when the destination must reflect archival.
|
|
816
|
+
*/
|
|
817
|
+
EXCLUDE_FROM_LOAD = 'exclude-from-load',
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
/**
|
|
821
|
+
* A REMOTE_REFERENCE mapping entry (#1684): a remote reference field written as a real LOCAL foreign key.
|
|
822
|
+
*
|
|
823
|
+
* ## What the local field holds
|
|
824
|
+
*
|
|
825
|
+
* - a target that is another PIPELINE destination on the same system of record (or this one — a
|
|
826
|
+
* self-reference such as Odoo `res.partner.parent_id`): the target's local row id, found by synthesizing
|
|
827
|
+
* the target's key with THE TARGET BINDING's key codec and looking it up on the target's
|
|
828
|
+
* `remoteKeyLocalField`;
|
|
829
|
+
* - a target that is a VIRTUAL (read-through) resource bound to the same system of record: the synthesized
|
|
830
|
+
* key itself — a virtual row's `_id` IS that value, so nothing is looked up.
|
|
831
|
+
*
|
|
832
|
+
* ## When it is written
|
|
833
|
+
*
|
|
834
|
+
* After the load, in its own phase — never inside the row transform. So a child extracted before its
|
|
835
|
+
* parent, a self-reference, and a cycle between two pipelines all resolve without ordering anything. The
|
|
836
|
+
* resolution phase is the ONLY writer of the local field: the load never touches it, which is why the field
|
|
837
|
+
* is left out of the load's managed fields.
|
|
838
|
+
*
|
|
839
|
+
* ## What the declaration owes (checked at authoring and at startup)
|
|
840
|
+
*
|
|
841
|
+
* - `localField` is the foreign key of a declared relationship between this resource and `targetResourceType`,
|
|
842
|
+
* a STRING field that accepts absence (an unresolved reference leaves it empty), and — like every
|
|
843
|
+
* pipeline-written field — `.excludeFromCreate().excludeFromUpdate()`;
|
|
844
|
+
* - the target is a pipeline destination or a virtual resource on THIS pipeline's system of record, keyed by
|
|
845
|
+
* ONE key field (a composite target key is a recorded widening);
|
|
846
|
+
* - when the target's orphan policy DELETES rows and the relationship tears children down with their parent,
|
|
847
|
+
* `orphanCascadeAcknowledged: true` — a row vanishing from the target's source would otherwise take this
|
|
848
|
+
* resource's rows with it through the ordinary `onParentDelete` rules, and nothing about this declaration
|
|
849
|
+
* says so unless the author does.
|
|
850
|
+
*/
|
|
851
|
+
export const ExternalDataRemoteReferenceMappingEntrySchema = z.strictObject({
|
|
852
|
+
kind: z.literal(ExternalDataMappingEntryKind.REMOTE_REFERENCE),
|
|
853
|
+
/** The remote field carrying the reference (`parent_id` on Odoo `res.partner`). */
|
|
854
|
+
remoteField: z.string().trim().min(1),
|
|
855
|
+
/** The local foreign-key field the resolved reference is written to. */
|
|
856
|
+
localField: z.string().trim().min(1),
|
|
857
|
+
/** The LOCAL resource the reference resolves to — a pipeline destination or a virtual resource. */
|
|
858
|
+
targetResourceType: z.string().trim().min(1),
|
|
859
|
+
/**
|
|
860
|
+
* How the remote value becomes the target's key. Absent = resolved at AUTHORING from the source dialect:
|
|
861
|
+
* `ODOO_MANY2ONE` on an Odoo source, `SCALAR` otherwise — the resource factory writes the resolved value
|
|
862
|
+
* into the declaration, exactly as it resolves the Odoo absent-as-false coercion.
|
|
863
|
+
*/
|
|
864
|
+
valueShape: z.enum(ExternalDataRemoteReferenceValueShape).optional(),
|
|
865
|
+
unresolved: z.enum(ExternalDataUnresolvedReferencePolicy).default(ExternalDataUnresolvedReferencePolicy.LEAVE_PENDING),
|
|
866
|
+
/**
|
|
867
|
+
* The author has read that the target's `orphanPolicy: DELETE` will cascade into this resource's rows
|
|
868
|
+
* through the relationship's `onParentDelete` teardown, and wants that. Only meaningful — and only
|
|
869
|
+
* demanded — when both are true; see the schema's header.
|
|
870
|
+
*/
|
|
871
|
+
orphanCascadeAcknowledged: z.boolean().default(false),
|
|
872
|
+
/** Which side owns the reference — BIDIRECTIONAL pipelines only (#1723). Absent = REMOTE. */
|
|
873
|
+
owner: z.enum(ExternalDataFieldOwner).optional(),
|
|
874
|
+
});
|
|
875
|
+
|
|
876
|
+
export type ExternalDataRemoteReferenceMappingEntry = z.infer<typeof ExternalDataRemoteReferenceMappingEntrySchema>;
|
|
877
|
+
|
|
878
|
+
/**
|
|
879
|
+
* A remote SCALAR a declared expression compares against or maps from (#1685) — the value shapes a remote field
|
|
880
|
+
* carries that can be matched exactly. An Odoo selection is a string, a status code may be a number, a flag a
|
|
881
|
+
* boolean. Objects and arrays (an Odoo many2one pair) cannot be matched and are not declarable.
|
|
882
|
+
*/
|
|
883
|
+
const externalDataExpressionScalarSchema = z.union([z.string(), z.number().finite(), z.boolean()]);
|
|
884
|
+
|
|
885
|
+
/**
|
|
886
|
+
* An `ENUM_MAP` entry (#1685): one remote code → one member of the local field's enum.
|
|
887
|
+
*
|
|
888
|
+
* - the local field is an ENUM, and every declared `localValue` (and the default's) is one of its members — checked
|
|
889
|
+
* at startup, so a renamed member fails the boot rather than every row;
|
|
890
|
+
* - an ABSENT remote value (the field unset: `null`, missing, or Odoo's `false` when `false` is not itself a declared
|
|
891
|
+
* code) lands null, or rejects the row when `required`;
|
|
892
|
+
* - a PRESENT code the declaration does not name follows `unmapped`: rejected by default, or the declared member.
|
|
893
|
+
*/
|
|
894
|
+
export const ExternalDataEnumMappingEntrySchema = z.strictObject({
|
|
895
|
+
kind: z.literal(ExternalDataMappingEntryKind.ENUM_MAP),
|
|
896
|
+
/** The remote field carrying the code (`state` on Odoo `account.move`). */
|
|
897
|
+
remoteField: z.string().trim().min(1),
|
|
898
|
+
localField: z.string().trim().min(1),
|
|
899
|
+
/** Every code the declaration maps, each to one member of the local enum. Codes are unique. */
|
|
900
|
+
values: z.array(z.strictObject({
|
|
901
|
+
remoteValue: externalDataExpressionScalarSchema,
|
|
902
|
+
localValue: z.union([z.string().min(1), z.number().finite()]),
|
|
903
|
+
})).min(1),
|
|
904
|
+
/** A PRESENT code no `values` entry names. Absent = reject the row. */
|
|
905
|
+
unmapped: z.discriminatedUnion('policy', [
|
|
906
|
+
z.strictObject({ policy: z.literal(ExternalDataUnmappedValuePolicy.REJECT_ROW) }),
|
|
907
|
+
z.strictObject({ policy: z.literal(ExternalDataUnmappedValuePolicy.USE_DEFAULT), localValue: z.union([z.string().min(1), z.number().finite()]) }),
|
|
908
|
+
]).default({ policy: ExternalDataUnmappedValuePolicy.REJECT_ROW }),
|
|
909
|
+
/** `true`: a row whose remote code is ABSENT is rejected. `false` (default): absence lands null. */
|
|
910
|
+
required: z.boolean().default(false),
|
|
911
|
+
});
|
|
912
|
+
|
|
913
|
+
export type ExternalDataEnumMappingEntry = z.infer<typeof ExternalDataEnumMappingEntrySchema>;
|
|
914
|
+
|
|
915
|
+
/**
|
|
916
|
+
* A `CONCATENATION` entry (#1685): remote fields and literals joined into one local STRING.
|
|
917
|
+
*
|
|
918
|
+
* Every part with a value is written, in order, joined by `separator`; a remote part whose value is absent or empty
|
|
919
|
+
* (`null`, missing, `''`, or Odoo's `false`) is DROPPED with its separator, the way SQL's `concat_ws` ignores a NULL
|
|
920
|
+
* argument — so `first` + `last` joined by a space yields `'Ada'`, never `'Ada '`, when the last name is unset. A
|
|
921
|
+
* number is written as JavaScript's shortest round-trip text (`42`, `12.5`; exponent notation only beyond `1e21` or
|
|
922
|
+
* below `1e-6`); any other value (a boolean off Odoo, a many2one pair) rejects the row.
|
|
923
|
+
*
|
|
924
|
+
* spec-cite: PostgreSQL 17 documentation, §9.4 "String Functions and Operators", `concat_ws` — "NULL arguments are
|
|
925
|
+
* ignored" (https://www.postgresql.org/docs/17/functions-string.html).
|
|
926
|
+
*
|
|
927
|
+
* When NO remote part has a value, the result is ABSENT — literals alone are decoration, not data — and lands null,
|
|
928
|
+
* or rejects the row when `required`.
|
|
929
|
+
*/
|
|
930
|
+
export const ExternalDataConcatenationMappingEntrySchema = z.strictObject({
|
|
931
|
+
kind: z.literal(ExternalDataMappingEntryKind.CONCATENATION),
|
|
932
|
+
localField: z.string().trim().min(1),
|
|
933
|
+
/** At least two parts, at least one of them a remote field. */
|
|
934
|
+
parts: z.array(z.discriminatedUnion('kind', [
|
|
935
|
+
z.strictObject({ kind: z.literal(ExternalDataConcatenationPartKind.REMOTE_FIELD), remoteField: z.string().trim().min(1) }),
|
|
936
|
+
z.strictObject({ kind: z.literal(ExternalDataConcatenationPartKind.LITERAL), literal: z.string().min(1) }),
|
|
937
|
+
])).min(2),
|
|
938
|
+
/** Written between two parts that both have a value. Default: nothing. */
|
|
939
|
+
separator: z.string().default(''),
|
|
940
|
+
required: z.boolean().default(false),
|
|
941
|
+
});
|
|
942
|
+
|
|
943
|
+
export type ExternalDataConcatenationMappingEntry = z.infer<typeof ExternalDataConcatenationMappingEntrySchema>;
|
|
944
|
+
|
|
945
|
+
/**
|
|
946
|
+
* An `ARITHMETIC` entry (#1685): `remote × factor + offset` onto a local NUMBER.
|
|
947
|
+
*
|
|
948
|
+
* A currency conversion is legal only as a DECLARED rate (`factor`): a live exchange rate is a second source, which
|
|
949
|
+
* is a join, and joins are a later widening. The declaration is the rate's record, so changing it changes the
|
|
950
|
+
* pipeline's extraction fingerprint and an incremental pipeline re-reads every row under the new rate.
|
|
951
|
+
*
|
|
952
|
+
* The remote value is a finite number, or a string holding a plain decimal numeral (`'12.50'` — how OData v2 and
|
|
953
|
+
* several REST APIs serialize decimals). Anything else rejects the row. `decimalPlaces` rounds the RESULT half away
|
|
954
|
+
* from zero, in binary floating point: it keeps `0.1 × 3` from landing as `0.30000000000000004`, and it does not make
|
|
955
|
+
* the value exact — an amount that must be exact to the cent belongs in a type this expression does not produce.
|
|
956
|
+
*/
|
|
957
|
+
export const ExternalDataArithmeticMappingEntrySchema = z.strictObject({
|
|
958
|
+
kind: z.literal(ExternalDataMappingEntryKind.ARITHMETIC),
|
|
959
|
+
remoteField: z.string().trim().min(1),
|
|
960
|
+
localField: z.string().trim().min(1),
|
|
961
|
+
/** Multiplier. Never 0 — a constant result is a `CONSTANT` entry. */
|
|
962
|
+
factor: z.number().finite().default(1),
|
|
963
|
+
/** Added after the multiplication. */
|
|
964
|
+
offset: z.number().finite().default(0),
|
|
965
|
+
/** Round the result to this many decimal places. Absent = no rounding. */
|
|
966
|
+
decimalPlaces: z.number().int().min(0).max(12).optional(),
|
|
967
|
+
required: z.boolean().default(false),
|
|
968
|
+
});
|
|
969
|
+
|
|
970
|
+
export type ExternalDataArithmeticMappingEntry = z.infer<typeof ExternalDataArithmeticMappingEntrySchema>;
|
|
971
|
+
|
|
972
|
+
/** What a `CONDITIONAL` case (or its `otherwise`) writes (#1685). */
|
|
973
|
+
const ExternalDataConditionalOutcomeSchema = z.discriminatedUnion('kind', [
|
|
974
|
+
z.strictObject({ kind: z.literal(ExternalDataConditionalOutcomeKind.CONSTANT), constant: externalDataExpressionScalarSchema }),
|
|
975
|
+
z.strictObject({
|
|
976
|
+
kind: z.literal(ExternalDataConditionalOutcomeKind.REMOTE_FIELD),
|
|
977
|
+
remoteField: z.string().trim().min(1),
|
|
978
|
+
/** As on a `REMOTE_FIELD` entry: Odoo's absent-as-false is resolved at authoring from the local field's type. */
|
|
979
|
+
coercion: z.enum(ExternalDataFieldCoercion).default(ExternalDataFieldCoercion.NONE),
|
|
980
|
+
}),
|
|
981
|
+
]);
|
|
982
|
+
|
|
983
|
+
export type ExternalDataConditionalOutcome = z.infer<typeof ExternalDataConditionalOutcomeSchema>;
|
|
984
|
+
|
|
985
|
+
/**
|
|
986
|
+
* A `CONDITIONAL` entry (#1685): the local value chosen by ONE remote field's value.
|
|
987
|
+
*
|
|
988
|
+
* The cases are tried in order and the first whose `equals` is exactly (`===`) the remote value wins; no case
|
|
989
|
+
* matching — an absent value included — takes `otherwise`. On an Odoo source an unset field reads `false`, so a declared
|
|
990
|
+
* `equals: false` case catches it before `otherwise` does. An outcome is a constant (checked against the local
|
|
991
|
+
* field's type, and against its members when it is an enum) or another remote field's value. Conditions over two
|
|
992
|
+
* fields, ranges and patterns are not part of the set: they are exactly what makes an expression language grow into
|
|
993
|
+
* the open function slot this set exists to avoid.
|
|
994
|
+
*/
|
|
995
|
+
export const ExternalDataConditionalMappingEntrySchema = z.strictObject({
|
|
996
|
+
kind: z.literal(ExternalDataMappingEntryKind.CONDITIONAL),
|
|
997
|
+
/** The remote field whose value decides. */
|
|
998
|
+
remoteField: z.string().trim().min(1),
|
|
999
|
+
localField: z.string().trim().min(1),
|
|
1000
|
+
cases: z.array(z.strictObject({ equals: externalDataExpressionScalarSchema, then: ExternalDataConditionalOutcomeSchema })).min(1),
|
|
1001
|
+
otherwise: ExternalDataConditionalOutcomeSchema,
|
|
1002
|
+
});
|
|
1003
|
+
|
|
1004
|
+
export type ExternalDataConditionalMappingEntry = z.infer<typeof ExternalDataConditionalMappingEntrySchema>;
|
|
1005
|
+
|
|
1006
|
+
/**
|
|
1007
|
+
* One declared T-step: remote field → local field with a built-in coercion, a constant, a resolved reference, or one
|
|
1008
|
+
* of the four declared expressions (#1685).
|
|
1009
|
+
*
|
|
1010
|
+
* Every entry shape is STRICT: an unknown key is refused, not dropped. That is what makes the refusal of an open
|
|
1011
|
+
* function slot real — `{ kind: 'remote-field', …, transform: (value) => … }` used to parse with `transform` silently
|
|
1012
|
+
* stripped, a declaration that reads as if it ran code and runs none.
|
|
1013
|
+
*/
|
|
378
1014
|
export const ExternalDataFieldMappingEntrySchema = z.discriminatedUnion('kind', [
|
|
379
|
-
z.
|
|
1015
|
+
z.strictObject({
|
|
380
1016
|
kind: z.literal(ExternalDataMappingEntryKind.REMOTE_FIELD),
|
|
381
1017
|
remoteField: z.string().trim().min(1),
|
|
382
1018
|
localField: z.string().trim().min(1),
|
|
@@ -387,19 +1023,189 @@ export const ExternalDataFieldMappingEntrySchema = z.discriminatedUnion('kind',
|
|
|
387
1023
|
* which the declaration coherence requires the local field to accept.
|
|
388
1024
|
*/
|
|
389
1025
|
required: z.boolean().default(false),
|
|
1026
|
+
/** Which side owns the field — BIDIRECTIONAL pipelines only (#1723). Absent = REMOTE. */
|
|
1027
|
+
owner: z.enum(ExternalDataFieldOwner).optional(),
|
|
390
1028
|
}),
|
|
391
|
-
z.
|
|
1029
|
+
z.strictObject({
|
|
392
1030
|
kind: z.literal(ExternalDataMappingEntryKind.CONSTANT),
|
|
393
1031
|
localField: z.string().trim().min(1),
|
|
394
1032
|
constant: z.union([z.string(), z.number(), z.boolean()]),
|
|
395
1033
|
}),
|
|
1034
|
+
ExternalDataRemoteReferenceMappingEntrySchema,
|
|
1035
|
+
ExternalDataEnumMappingEntrySchema,
|
|
1036
|
+
ExternalDataConcatenationMappingEntrySchema,
|
|
1037
|
+
ExternalDataArithmeticMappingEntrySchema,
|
|
1038
|
+
ExternalDataConditionalMappingEntrySchema,
|
|
396
1039
|
]);
|
|
1040
|
+
|
|
1041
|
+
/**
|
|
1042
|
+
* HOW a source says what changed — one member per remote change-tracking mechanism (#1682).
|
|
1043
|
+
*
|
|
1044
|
+
* A closed vocabulary shared by two parties: a system-of-record VENDOR FACET declares which modes its
|
|
1045
|
+
* deployments support (`incrementalExtractionModes`), and a pipeline declaration chooses one. A
|
|
1046
|
+
* pipeline asking for a mode its source's facet does not declare is refused at startup, naming both.
|
|
1047
|
+
*
|
|
1048
|
+
* Three modes: Odoo's `write_date`, and the two OData v4 mechanisms (#1722) — a modified-at filter and
|
|
1049
|
+
* the delta-link protocol. The incremental TRACK on the state row is mode-neutral (its watermark and
|
|
1050
|
+
* cursor are opaque, mode-owned text), so a new mode needed no reshape of it.
|
|
1051
|
+
*/
|
|
1052
|
+
export enum ExternalDataIncrementalExtractionMode {
|
|
1053
|
+
/**
|
|
1054
|
+
* Odoo's `write_date` — the "Last Updated on" column the ORM maintains on every model that logs
|
|
1055
|
+
* access. Read in (SECOND, id) order from a watermark, with a declared lookback. See
|
|
1056
|
+
* {@link ExternalDataIncrementalExtractionDeclarationSchema}.
|
|
1057
|
+
*/
|
|
1058
|
+
ODOO_WRITE_DATE = 'odoo-write-date',
|
|
1059
|
+
/**
|
|
1060
|
+
* OData v4, a MODIFIED-AT property the declaration names (`modifiedAtRemoteField` — per entity, not per
|
|
1061
|
+
* vendor: Dataverse's `modifiedon`, Business Central's `lastModifiedDateTime`). Rows with that property at
|
|
1062
|
+
* or after the watermark (less the lookback) are read in KEY order, and the watermark moves only when the
|
|
1063
|
+
* pass completes. Catches no deletions: full passes find those.
|
|
1064
|
+
*/
|
|
1065
|
+
ODATA_MODIFIED_AT = 'odata-modified-at',
|
|
1066
|
+
/**
|
|
1067
|
+
* OData v4 CHANGE TRACKING: the first pass asks for `Prefer: odata.track-changes` and keeps the service's
|
|
1068
|
+
* `@odata.deltaLink`; every later pass follows it and receives changed entities AND deleted ones, so an
|
|
1069
|
+
* incremental pass applies the orphan policy to each deleted key. The vendor must track changes for the
|
|
1070
|
+
* entity set (Dataverse: per table).
|
|
1071
|
+
*/
|
|
1072
|
+
ODATA_DELTA_LINK = 'odata-delta-link',
|
|
1073
|
+
}
|
|
1074
|
+
|
|
1075
|
+
/**
|
|
1076
|
+
* `incremental` — read only what changed between full passes (#1682).
|
|
1077
|
+
*
|
|
1078
|
+
* ## What an incremental pass does, and what it never does
|
|
1079
|
+
*
|
|
1080
|
+
* - It reads the rows changed since the pipeline's WATERMARK — the largest remote position a previous
|
|
1081
|
+
* incremental pass actually LOADED, never the local clock (a local clock and a remote clock disagree,
|
|
1082
|
+
* and the gap is rows nobody reads).
|
|
1083
|
+
* - The watermark advances only after the rows that reached it are loaded. A crash re-reads; it never
|
|
1084
|
+
* skips.
|
|
1085
|
+
* - It NEVER detects deletions. A row deleted remotely does not "change", so no incremental read can
|
|
1086
|
+
* see it. Deletions are found by FULL passes only, on `fullPassCron` — which is why that cadence is
|
|
1087
|
+
* required rather than optional: an incremental-only pipeline would keep deleted rows forever.
|
|
1088
|
+
* - It runs on the pipeline's `scheduleCron`, which is therefore required too.
|
|
1089
|
+
*
|
|
1090
|
+
* ## The Odoo mode — why (second, id), and why a lookback
|
|
1091
|
+
*
|
|
1092
|
+
* Odoo STORES `write_date` with microseconds (the writing transaction's `now()`) and SERVES it cut to
|
|
1093
|
+
* the second, while a domain compares the stored value. Two obvious designs fail on that gap:
|
|
1094
|
+
* `write_date > w` skips the rows that share the last row's second but did not fit on the page, and a
|
|
1095
|
+
* keyset on the served `(write_date, id)` re-reads its own last row forever, because a row served as
|
|
1096
|
+
* `10:00:00` is stored after `10:00:00`. The extraction therefore walks (SECOND, id): it finishes one
|
|
1097
|
+
* second by id (`s <= write_date < s+1s AND id > i`, ordered by id), then finds the next rows from the
|
|
1098
|
+
* following second. Every row is read once per pass, however many rows share a second.
|
|
1099
|
+
* spec-cite: N/A — Odoo 17.0 SOURCE, not a document: `odoo/models.py`
|
|
1100
|
+
* `vals.setdefault('write_date', self.env.cr.now())`, `odoo/sql_db.py` `Cursor.now`
|
|
1101
|
+
* (`SELECT (now() AT TIME ZONE 'UTC')`), `odoo/fields.py` `Datetime.to_string` (`strftime`), and no
|
|
1102
|
+
* `Datetime.convert_to_column` override (the base field stores the full value).
|
|
1103
|
+
*
|
|
1104
|
+
* The lookback re-reads the last `lookbackSeconds` of changes at the START of every incremental pass.
|
|
1105
|
+
* Odoo stamps `write_date` when the writing transaction runs, not when it commits, so a long
|
|
1106
|
+
* transaction can commit a row whose `write_date` is already older than a watermark another pass
|
|
1107
|
+
* advanced past in the meantime; without a lookback that row is never read — and a transaction that
|
|
1108
|
+
* commits later inside the watermark's own second is caught the same way. Re-reads are free where it
|
|
1109
|
+
* matters: the load compares content and writes nothing for an unchanged row. UNVERIFIED against a
|
|
1110
|
+
* live Odoo — the default is a margin, not a measurement; raise it for a deployment with long batch
|
|
1111
|
+
* jobs. `0` is NOT a harmless setting: without a lookback, a row written later inside a second a pass
|
|
1112
|
+
* has already finished is read only when it changes again (or by a full pass).
|
|
1113
|
+
*
|
|
1114
|
+
* ## Changing the declaration resets the incremental track
|
|
1115
|
+
*
|
|
1116
|
+
* An incremental pass never re-reads a row that did not change remotely, so a change to what is
|
|
1117
|
+
* extracted or how it is loaded — the binding, key fields, mapping, `sourceFilter`, partition fields,
|
|
1118
|
+
* archived-record treatment, or the operator's partition ASSIGNMENTS — would otherwise never reach the
|
|
1119
|
+
* rows already loaded. The run fingerprints those inputs; a different fingerprint drops the watermark,
|
|
1120
|
+
* and the next incremental pass reads the whole source again. The run summary says it did.
|
|
1121
|
+
*/
|
|
1122
|
+
export const ExternalDataIncrementalExtractionDeclarationSchema = z.discriminatedUnion('mode', [
|
|
1123
|
+
z.object({
|
|
1124
|
+
mode: z.literal(ExternalDataIncrementalExtractionMode.ODOO_WRITE_DATE),
|
|
1125
|
+
/**
|
|
1126
|
+
* When FULL passes run (cron). The only deletion detector, so required. A full pass that takes
|
|
1127
|
+
* several runs continues on `scheduleCron` ticks until it completes, interleaved with incremental
|
|
1128
|
+
* passes; neither track waits for the other.
|
|
1129
|
+
*/
|
|
1130
|
+
fullPassCron: z.string().trim().min(1),
|
|
1131
|
+
/** Seconds of changes re-read at the start of every incremental pass (see above). Up to one day. */
|
|
1132
|
+
lookbackSeconds: z.number().int().nonnegative().max(86_400).default(300),
|
|
1133
|
+
}),
|
|
1134
|
+
/*
|
|
1135
|
+
* ## The OData modified-at mode (#1722)
|
|
1136
|
+
*
|
|
1137
|
+
* `$filter=<modifiedAtRemoteField> ge <watermark − lookback>`, ordered by the KEY as a full pass is, paged
|
|
1138
|
+
* by the service. Because the pages are in key order and not in modified-at order, a page's largest
|
|
1139
|
+
* timestamp says nothing about the rows still to come, so the watermark moves only when the PASS completes
|
|
1140
|
+
* (to the largest timestamp the pass read), never per page — a per-page watermark would skip the rows of
|
|
1141
|
+
* a later page modified before it. `ge`, not `gt`: two rows sharing the watermark's instant are both read.
|
|
1142
|
+
*
|
|
1143
|
+
* The property must be an `Edm.DateTimeOffset` the service filters on. The lookback plays the role it
|
|
1144
|
+
* plays for Odoo: a row written by a transaction that commits after the pass read past its timestamp is
|
|
1145
|
+
* re-read by the next pass. Changing `modifiedAtRemoteField` starts the track over (the stored watermark
|
|
1146
|
+
* names the property it was read on).
|
|
1147
|
+
*/
|
|
1148
|
+
z.object({
|
|
1149
|
+
mode: z.literal(ExternalDataIncrementalExtractionMode.ODATA_MODIFIED_AT),
|
|
1150
|
+
fullPassCron: z.string().trim().min(1),
|
|
1151
|
+
/** The entity's modified-at property (`Edm.DateTimeOffset`), by its REMOTE name. */
|
|
1152
|
+
modifiedAtRemoteField: z.string().trim().min(1),
|
|
1153
|
+
lookbackSeconds: z.number().int().nonnegative().max(86_400).default(300),
|
|
1154
|
+
}),
|
|
1155
|
+
/*
|
|
1156
|
+
* ## The OData delta-link mode (#1722)
|
|
1157
|
+
*
|
|
1158
|
+
* The first incremental pass reads the whole entity set with `Prefer: odata.track-changes` and keeps the
|
|
1159
|
+
* `@odata.deltaLink` the service puts on its last page; each later pass GETs that link and receives what
|
|
1160
|
+
* changed and what was DELETED since. A deleted entity carries only its id, so the orphan policy is applied
|
|
1161
|
+
* to that key — an incremental pass that finds deletions, which the other modes cannot.
|
|
1162
|
+
*
|
|
1163
|
+
* Refused at declaration: a `sourceFilter` (Dataverse refuses `$filter`, `$orderby`, `$expand` and `$top`
|
|
1164
|
+
* with change tracking) and a composite key (a deleted entity names one id). A delta link the service no
|
|
1165
|
+
* longer honours (`410 Gone`) resets the track and the same run falls back to a FULL pass, which is what
|
|
1166
|
+
* finds the deletions the expired link would have reported; the run summary says so.
|
|
1167
|
+
* spec-cite: Microsoft Learn, "Use change tracking to synchronize data with external systems"
|
|
1168
|
+
* (https://learn.microsoft.com/en-us/power-apps/developer/data-platform/use-change-tracking-synchronize-data-external-systems),
|
|
1169
|
+
* "Query options not supported in Change Tracking Web API request" — "System query options $filter,
|
|
1170
|
+
* $orderby, $expand, and $top aren't supported when you use the Prefer: odata.track-changes header".
|
|
1171
|
+
* spec-cite: OData Version 4.01 Part 1: Protocol §9.2.4 — "410 Gone indicates that the requested resource is
|
|
1172
|
+
* no longer available. This can happen if a client has waited too long to follow a delta link".
|
|
1173
|
+
*
|
|
1174
|
+
* No lookback: a delta link is the service's own position, not a clock.
|
|
1175
|
+
*/
|
|
1176
|
+
z.object({
|
|
1177
|
+
mode: z.literal(ExternalDataIncrementalExtractionMode.ODATA_DELTA_LINK),
|
|
1178
|
+
fullPassCron: z.string().trim().min(1),
|
|
1179
|
+
}),
|
|
1180
|
+
]);
|
|
1181
|
+
|
|
1182
|
+
export type ExternalDataIncrementalExtractionDeclaration = z.infer<typeof ExternalDataIncrementalExtractionDeclarationSchema>;
|
|
1183
|
+
|
|
1184
|
+
/**
|
|
1185
|
+
* The dialect each incremental mode is spoken over. A `Record` over the enum so a mode added without
|
|
1186
|
+
* its dialect is a compile error rather than a declaration the coherence check silently waves through.
|
|
1187
|
+
*/
|
|
1188
|
+
export const EXTERNAL_DATA_INCREMENTAL_MODE_DIALECT: Readonly<Record<ExternalDataIncrementalExtractionMode, HttpApiTransportDialect>> = {
|
|
1189
|
+
[ExternalDataIncrementalExtractionMode.ODOO_WRITE_DATE]: HttpApiTransportDialect.ODOO_JSONRPC,
|
|
1190
|
+
[ExternalDataIncrementalExtractionMode.ODATA_MODIFIED_AT]: HttpApiTransportDialect.ODATA,
|
|
1191
|
+
[ExternalDataIncrementalExtractionMode.ODATA_DELTA_LINK]: HttpApiTransportDialect.ODATA,
|
|
1192
|
+
};
|
|
397
1193
|
```
|
|
398
1194
|
|
|
399
1195
|
### Origin Package: `@wildo-ai/saas-models`
|
|
400
1196
|
|
|
401
1197
|
```typescript
|
|
402
1198
|
export const ExternalDataPipelineDeclarationSchema = z.object({
|
|
1199
|
+
/**
|
|
1200
|
+
* Which way rows travel — see {@link ExternalDataPipelineDirection}. `INBOUND` when omitted.
|
|
1201
|
+
*
|
|
1202
|
+
* An OUTBOUND pipeline (#1690) reuses this whole declaration with the arrows reversed: the binding opens the writes
|
|
1203
|
+
* it sends (`writableVerbs: [CREATE, UPDATE]`, with the same `writeConcurrency` a read-through binding states), each
|
|
1204
|
+
* `mapping` entry names the local field SENT and the remote field it lands on, and `remoteKeyLocalField` receives the
|
|
1205
|
+
* key the system of record assigns when it creates the row. The fields that only describe reading a source —
|
|
1206
|
+
* `sourceFilter`, `incremental`, `archivedRecords`, `partitionKeyLocalField`, `population`, `orphanPolicy` — are
|
|
1207
|
+
* refused on it, because nothing would read them.
|
|
1208
|
+
*/
|
|
403
1209
|
direction: z.enum(ExternalDataPipelineDirection).default(ExternalDataPipelineDirection.INBOUND),
|
|
404
1210
|
|
|
405
1211
|
/**
|
|
@@ -412,6 +1218,14 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
|
|
|
412
1218
|
* different thing that no binding names), so a pipeline extracts the operator's rows and the
|
|
413
1219
|
* destination's own scope declaration decides who may then read them.
|
|
414
1220
|
*
|
|
1221
|
+
* How the source is WALKED is the dialect's, and only drift-safe walks are admitted: OData v4 follows
|
|
1222
|
+
* the server's `@odata.nextLink`; OData v2 (`ODATA_V2`, #1687) walks the binding's key fields and never
|
|
1223
|
+
* follows `__next`, because v2 promises no stability across a partial listing; Odoo walks its id keyset;
|
|
1224
|
+
* and a REST_JSON source walks the KEYSET its `list` statement declares
|
|
1225
|
+
* (`operations.list.statement.keyset: { keyRemoteField }`, #1686) — the engine builds "the next N rows
|
|
1226
|
+
* after the last key, in key order" and stores that key as the cursor.
|
|
1227
|
+
* A REST source with no keyset (offset paging only) is refused.
|
|
1228
|
+
*
|
|
415
1229
|
* ⚠ OPERATIONAL HAZARD (PR-16): changing `keyFields` or a component CODEC after rows exist
|
|
416
1230
|
* re-keys EVERY business key — the whole destination population orphans and re-creates on the
|
|
417
1231
|
* next full pass, detaching local annotations (extension fields, files, chunks) from the rows
|
|
@@ -427,6 +1241,13 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
|
|
|
427
1241
|
* plain STRING business key. The factory requires it declared `.isBusinessKey()` +
|
|
428
1242
|
* `excludeFromCreate/Update`: SYNC's idempotent upsert keys on it, and no caller may mint or
|
|
429
1243
|
* move it.
|
|
1244
|
+
*
|
|
1245
|
+
* On an OUTBOUND pipeline (#1690) it is empty until the row is first sent: the engine writes the key the system of
|
|
1246
|
+
* record answers the create with, exactly once, and then updates the remote row it names. It must therefore accept
|
|
1247
|
+
* absence, and it is still excluded from create and update — a caller that could write it could point a local row at
|
|
1248
|
+
* any remote record. It must be `.isUnique()` (global, sparse — the default) and `.optional()`, never `.nullable()`:
|
|
1249
|
+
* one remote record, one local row, enforced by the store on every path that writes the key, while the rows not yet
|
|
1250
|
+
* sent (no key) stay outside the index. No business key is required there: nothing upserts on it.
|
|
430
1251
|
*/
|
|
431
1252
|
remoteKeyLocalField: z.string().trim().min(1),
|
|
432
1253
|
|
|
@@ -476,20 +1297,72 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
|
|
|
476
1297
|
|
|
477
1298
|
population: z.enum(ExternalDataDestinationPopulation).default(ExternalDataDestinationPopulation.CLOSED),
|
|
478
1299
|
|
|
1300
|
+
/**
|
|
1301
|
+
* Odoo sources only: whether ARCHIVED remote rows are loaded (#1732). Absent = `LOAD`. Archived rows
|
|
1302
|
+
* are extracted and counted as observed under every treatment, so archiving a record in Odoo never
|
|
1303
|
+
* reaches the orphan policy — see {@link ExternalDataArchivedRecordTreatment}.
|
|
1304
|
+
*/
|
|
1305
|
+
archivedRecords: ExternalDataArchivedRecordsDeclarationSchema.optional(),
|
|
1306
|
+
|
|
479
1307
|
orphanPolicy: z.enum(ExternalDataOrphanPolicy).default(ExternalDataOrphanPolicy.REPORT),
|
|
480
1308
|
|
|
1309
|
+
/**
|
|
1310
|
+
* What a BIDIRECTIONAL pipeline (#1723) does with a row whose BOTH-owned fields changed on both sides since they last
|
|
1311
|
+
* agreed — see {@link ExternalDataConflictPolicy}. Absent = REFUSE_AND_REPORT: nothing is overwritten that nobody
|
|
1312
|
+
* decided to overwrite. Refused on any other direction, where no field has two owners.
|
|
1313
|
+
*/
|
|
1314
|
+
conflictPolicy: z.enum(ExternalDataConflictPolicy).optional(),
|
|
1315
|
+
|
|
481
1316
|
/**
|
|
482
1317
|
* Cron expression for the scheduled refresh (crontabs machinery). Absent = on-demand only —
|
|
483
1318
|
* legal, and honest for a manually-driven backfill.
|
|
484
1319
|
*/
|
|
485
1320
|
scheduleCron: z.string().trim().min(1).optional(),
|
|
486
1321
|
|
|
1322
|
+
/**
|
|
1323
|
+
* Read only what changed between full passes (#1682). Absent = every pass is a FULL pass, the
|
|
1324
|
+
* behaviour of every pipeline before this existed. When declared, `scheduleCron` runs incremental
|
|
1325
|
+
* passes and `incremental.fullPassCron` runs the full passes that alone detect deletions — see
|
|
1326
|
+
* {@link ExternalDataIncrementalExtractionDeclarationSchema}.
|
|
1327
|
+
*/
|
|
1328
|
+
incremental: ExternalDataIncrementalExtractionDeclarationSchema.optional(),
|
|
1329
|
+
|
|
487
1330
|
/**
|
|
488
1331
|
* Extraction bound per run (v3.1 §2): a big backfill progresses across runs via the ledger's
|
|
489
1332
|
* resumable cursor instead of owning one unbounded run. The default matches the rate-budget
|
|
490
1333
|
* era's "bounded by construction" posture.
|
|
1334
|
+
*
|
|
1335
|
+
* A run ends on a PAGE boundary, so it may carry up to one page more than this — never fewer
|
|
1336
|
+
* rows than the pass has left, and never a page cut short: the source's continuation follows the
|
|
1337
|
+
* whole page, so rows cut from it would be read by no run. An OData v4 source asks for pages of
|
|
1338
|
+
* `min(maxRowsPerRun, 1000)` (`Prefer: odata.maxpagesize`), which a service may honour or not
|
|
1339
|
+
* (#1991). Whether a pass is COMPLETE is never decided from this number — only from the source
|
|
1340
|
+
* answering that nothing is left.
|
|
1341
|
+
*
|
|
1342
|
+
* It bounds a run's WORK, not its memory: a run loads and checkpoints each page (up to 1 000 rows)
|
|
1343
|
+
* before it reads the next (#1689), so it holds one page, and a run that fails part-way keeps the
|
|
1344
|
+
* pages it loaded — the next run resumes after them.
|
|
491
1345
|
*/
|
|
492
1346
|
maxRowsPerRun: z.number().int().positive().default(10_000),
|
|
1347
|
+
|
|
1348
|
+
/**
|
|
1349
|
+
* How long one run may spend before it stops at a page boundary (#1683) — the run's DEADLINE, in
|
|
1350
|
+
* milliseconds.
|
|
1351
|
+
*
|
|
1352
|
+
* A run PACES against its source's rate budget: when the binding's `remoteCallSemantics
|
|
1353
|
+
* .maxRequestsPerMinute` is full it waits for room instead of failing, and it waits as long as a
|
|
1354
|
+
* throttling source's `Retry-After` asks. This bounds that waiting. No wait that would end past the
|
|
1355
|
+
* deadline is taken and no page starts after it; the run then ends as a PARTIAL pass — every page it
|
|
1356
|
+
* loaded is kept and its cursor continues the pass on the next run — never as a failure.
|
|
1357
|
+
*
|
|
1358
|
+
* It bounds extraction and load together: each page is loaded before the next is read (#1689), so a
|
|
1359
|
+
* run finishes after the page it was working on, by at most one page's extraction and load.
|
|
1360
|
+
*
|
|
1361
|
+
* Fifteen minutes by default: well inside an hourly `scheduleCron`, and long enough that a pass of the
|
|
1362
|
+
* default `maxRowsPerRun` completes at even a small binding ceiling. Six hours at most — a run that
|
|
1363
|
+
* needs longer is a backfill, and resuming across runs is what the cursor is for.
|
|
1364
|
+
*/
|
|
1365
|
+
maxRunDurationMs: z.number().int().min(1_000).max(21_600_000).default(900_000),
|
|
493
1366
|
});
|
|
494
1367
|
```
|
|
495
1368
|
|
|
@@ -499,23 +1372,100 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
|
|
|
499
1372
|
authored vocabulary, and the coercions.
|
|
500
1373
|
- `references/framework-http-api-binding-api.md` — the virtual-resource binding contract and its
|
|
501
1374
|
stance vocabularies.
|
|
1375
|
+
- `references/read-through-writes.md` — writing rows back through a virtual resource: what to
|
|
1376
|
+
declare, who may write which partition, the Idempotency-Key and its one-day expiry, what an Odoo
|
|
1377
|
+
write sends and the limit of its best-effort version check, what an OData write sends (`POST` /
|
|
1378
|
+
`PATCH` / `DELETE`, `If-Match` on the entity tag) and the stable codes a client branches on.
|
|
1379
|
+
- `references/odata-v2-sources.md` — reading an OData v2 service (`ODATA_V2`): declaring it, why the
|
|
1380
|
+
engine reads the service's `$metadata`, the values it decodes and refuses, how a pipeline walks it by
|
|
1381
|
+
key rather than by `__next`, and what it cannot do.
|
|
1382
|
+
- `references/system-of-record-actions.md` — running a declared ERP action (Odoo `action_post`, an
|
|
1383
|
+
OData action): the declaration, who may run it on which record, its one HTTP door, and its codes.
|
|
502
1384
|
- `references/lane-selection.md` — the choice in Step 1 at more depth, including what each lane
|
|
503
1385
|
gives up and the industry precedent.
|
|
504
1386
|
- `references/pipeline-destination-schema.md` — the destination schema rules, and what each refusal
|
|
505
1387
|
message is telling you.
|
|
506
1388
|
- `references/framework-pipeline-admin-endpoints-api.md` — run a pipeline on demand while authoring
|
|
507
|
-
its mapping,
|
|
1389
|
+
its mapping, read what each one last did (`cursor`, `loadStatus`) and its health, list its run
|
|
1390
|
+
history with the rows each run refused (`GET …/runs`), and reset a pipeline whose run keeps
|
|
1391
|
+
refusing its stored state (`POST …/reset`).
|
|
1392
|
+
- `references/incremental-extraction.md` — reading only what changed: the two tracks, the Odoo
|
|
1393
|
+
`write_date` watermark and its lookback, the fingerprint that re-reads the source, and why a
|
|
1394
|
+
full-pass cadence is required.
|
|
1395
|
+
- `references/rate-budgets-and-pacing.md` — the instance budget and the binding ceiling, how a
|
|
1396
|
+
pipeline paces against them, `maxRunDurationMs`, how to size the numbers, and the measured load
|
|
1397
|
+
throughput a pass costs the store.
|
|
1398
|
+
- `references/erasure-suppression.md` — why an erased copied row is not re-imported, what a run counts,
|
|
1399
|
+
when a suppression is released, and the key-rotation refusal.
|
|
1400
|
+
- `references/declared-expressions.md` — `ENUM_MAP`, `CONCATENATION`, `ARITHMETIC`, `CONDITIONAL`: a
|
|
1401
|
+
local value derived from remote fields, what startup checks, why there is no transform function, and
|
|
1402
|
+
how an expression edit reaches rows an incremental pass would not re-read.
|
|
1403
|
+
- `references/remote-references.md` — `REMOTE_REFERENCE`: turning an Odoo many2one or an OData
|
|
1404
|
+
navigation key into a real local foreign key, the pending set, `REJECT_ROW`, and the orphan-cascade
|
|
1405
|
+
refusal.
|
|
1406
|
+
- `references/facet-augmentations.md` — adding a partition or a credential kind to a vendor facet a
|
|
1407
|
+
package does not own: the augmentation record, the per-instance `facetAugmentations` opt-in, and what
|
|
1408
|
+
is refused at boot.
|
|
1409
|
+
- `references/rest-keyset-sources.md` — a REST_JSON source (Salesforce SOQL, NetSuite SuiteQL) in a
|
|
1410
|
+
pipeline: the statement `keyset` you declare, the page the engine builds, why the cursor is a key and
|
|
1411
|
+
never a continuation link, and what is refused.
|
|
1412
|
+
- `references/outbound-pipelines.md` — `direction: OUTBOUND`: sending the application's own rows to a
|
|
1413
|
+
system of record — the declaration, the reversed field ownership, what each pass sends and never sends,
|
|
1414
|
+
partition placement, the unknown-outcome create that waits for an operator, and what a pass reports.
|
|
1415
|
+
- `references/provenance-cue.md` — the "synced from ⟨instance⟩ · as of ⟨pass⟩" note on pipeline-written
|
|
1416
|
+
fields: which fields carry it, what "as of" means, the read surface and instance label it needs, and
|
|
1417
|
+
who may read it.
|
|
508
1418
|
|
|
509
1419
|
## Verification
|
|
510
1420
|
|
|
511
1421
|
- [ ] The resource declares exactly one lane, not both.
|
|
512
1422
|
- [ ] Virtual: `keyFields` order is deliberate; `system` names a declared instance; `erasure` is stated.
|
|
1423
|
+
- [ ] A binding whose rows hold personal data names `purposeRefs` that exist in
|
|
1424
|
+
`operatorComplianceIdentity.lawfulBases`.
|
|
1425
|
+
- [ ] An instance whose resources hold personal data declares `personalDataOrigin`.
|
|
513
1426
|
- [ ] Virtual: the resource is ORGANIZATIONS-scoped and its primary-scope relationship is
|
|
514
1427
|
`REQUIRES_CONTEXT` with no `foreignKeyField` — the factory refuses anything else.
|
|
1428
|
+
- [ ] Virtual writes: every verb in `writableVerbs` has its operation, and every write operation's
|
|
1429
|
+
verb is in `writableVerbs`; no `*_MANY` operation, no `haveBulkOperation`, no `serviceRuntimeMode`.
|
|
1430
|
+
- [ ] Actions: each lives on the binding of the entity it acts on; a writing one is exposed only through a
|
|
1431
|
+
custom operation named in `actions.<name>.operation`, borrowing `UPDATE`, with
|
|
1432
|
+
`idempotencyKey: REQUIRED`, whose implementation calls `utils.systemOfRecordActions.run(...)`; no
|
|
1433
|
+
code reaches the ERP any other way.
|
|
1434
|
+
- [ ] Either lane: a binding declaring `erasure: NO_SUBJECT_DATA` brings no field that declares
|
|
1435
|
+
`.dataCategories()` (read-through: any field; pipeline: any mapped field).
|
|
1436
|
+
- [ ] Virtual writes: a field landing on the partition field is excluded from create and update.
|
|
1437
|
+
- [ ] Virtual writes: the client handles `SYSTEM_OF_RECORD_WRITE_OUTCOME_UNKNOWN` by reading the row,
|
|
1438
|
+
never by resending under a new key.
|
|
515
1439
|
- [ ] Pipeline: `remoteKeyLocalField` is a `.isBusinessKey()` string field.
|
|
516
1440
|
- [ ] Pipeline: every mapped local field is `.excludeFromCreate().excludeFromUpdate()`.
|
|
517
1441
|
- [ ] Pipeline: every non-`required` mapped field can accept absence (optional/nullable/defaulted).
|
|
1442
|
+
- [ ] Odoo pipeline: decide `archivedRecords` deliberately — the default loads archived records, so map
|
|
1443
|
+
`active` if the destination must show archival; archived records are never orphans either way.
|
|
1444
|
+
- [ ] Incremental pipeline: `scheduleCron` AND `incremental.fullPassCron` are both declared, and the
|
|
1445
|
+
full-pass cadence bounds how long a row deleted in the source may linger locally.
|
|
1446
|
+
- [ ] Pipeline on an instance that declares `maxRequestsPerMinute`: the binding declares
|
|
1447
|
+
`remoteCallSemantics.maxRequestsPerMinute` strictly below it, and `maxRunDurationMs` fits the
|
|
1448
|
+
pipeline's `scheduleCron` interval.
|
|
518
1449
|
- [ ] Pipeline: verify first and last batch keys remain present across a resumed pass; then remove a source row and verify the configured orphan policy. Check reconciliationStatus for skipped reconciliation and loadStatus for failed writes.
|
|
1450
|
+
- [ ] Pipeline holding personal data: erase one copied row, run a full pass, and confirm the row is not
|
|
1451
|
+
back as a live row and the run reports `suppressedRows: 1`.
|
|
1452
|
+
- [ ] REST_JSON pipeline source: the binding's `list` statement declares `keyset` on its single key
|
|
1453
|
+
field; a SOQL one declares `cursorPath`, a SuiteQL one `pagingParams` with
|
|
1454
|
+
`placement: 'query-string'`.
|
|
1455
|
+
- [ ] Pipeline with a `REMOTE_REFERENCE`: its `localField` is the `foreignKeyField` of a declared
|
|
1456
|
+
relationship to `targetResourceType`, optional, and excluded from create and update; after a full
|
|
1457
|
+
pass the child row's foreign key holds the parent's LOCAL id, and `pendingReferences` counts only
|
|
1458
|
+
references whose target is genuinely not loaded.
|
|
1459
|
+
- [ ] Pipeline with a declared expression: each `ENUM_MAP` targets a `z.enum(...)` field and maps
|
|
1460
|
+
every code the source sends today (a run reporting rejected rows names the field of an unmapped
|
|
1461
|
+
code); each `CONCATENATION` targets a string field, each `ARITHMETIC` a number field, and a
|
|
1462
|
+
currency conversion uses a declared `factor`.
|
|
1463
|
+
- [ ] OUTBOUND pipeline: `writableVerbs` includes `CREATE`; the mapped fields are caller-writable;
|
|
1464
|
+
`remoteKeyLocalField` is an optional (not nullable) `.isUnique()` string excluded from create and update; no sent field declares
|
|
1465
|
+
`.dataCategories()`; on a partitioned instance `partitionUnitLocalField` names the row's unit.
|
|
1466
|
+
- [ ] OUTBOUND pipeline: create a row, run a pass, and confirm the row gained its remote key and the
|
|
1467
|
+
record exists remotely; edit it, run again, and confirm exactly one update; a row of another
|
|
1468
|
+
organization is never sent (`droppedOtherOrganization`).
|
|
519
1469
|
- [ ] The application starts. Every rule above is checked at startup, by name.
|
|
520
1470
|
|
|
521
1471
|
### Grep invariants
|
|
@@ -529,6 +1479,24 @@ rg -A3 'externalDataPipeline' shared-lib/src --glob '*.resources-config.ts'
|
|
|
529
1479
|
|
|
530
1480
|
# Files or RAG declared on a virtual resource — neither can work without a local row.
|
|
531
1481
|
rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg 'z_file\(|ragSource\('
|
|
1482
|
+
|
|
1483
|
+
# Incremental pipelines — each must also carry scheduleCron and incremental.fullPassCron.
|
|
1484
|
+
rg -B2 -A4 'incremental:' shared-lib/src --glob '*.resources-config.ts'
|
|
1485
|
+
|
|
1486
|
+
# Remote references — each localField must be a declared relationship foreignKeyField to its target.
|
|
1487
|
+
rg -B1 -A4 'REMOTE_REFERENCE' shared-lib/src --glob '*.resources-config.ts'
|
|
1488
|
+
|
|
1489
|
+
# Declared expressions — each ENUM_MAP's localField must be an enum field, ARITHMETIC a number field.
|
|
1490
|
+
rg -B1 -A6 'ENUM_MAP|CONCATENATION|ARITHMETIC|CONDITIONAL' shared-lib/src --glob '*.resources-config.ts'
|
|
1491
|
+
|
|
1492
|
+
# Declared rate budgets — compare each pipeline's binding ceiling with its instance's (must be lower).
|
|
1493
|
+
rg -n 'maxRequestsPerMinute' wildo.saas.config.ts shared-lib/src
|
|
1494
|
+
|
|
1495
|
+
# OUTBOUND pipelines — each mapped field must be caller-writable and its remote key an optional string.
|
|
1496
|
+
rg -B2 -A12 'ExternalDataPipelineDirection.OUTBOUND' shared-lib/src --glob '*.resources-config.ts'
|
|
1497
|
+
|
|
1498
|
+
# Bulk write operations on a virtual resource — refused; a remote bulk write has no atomicity.
|
|
1499
|
+
rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg '_MANY|haveBulkOperation'
|
|
532
1500
|
```
|
|
533
1501
|
|
|
534
1502
|
## Common Rationalizations
|
|
@@ -539,6 +1507,15 @@ rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg 'z_file\(|ragSour
|
|
|
539
1507
|
| "I'll mark the synced fields writable and let users fix bad data." | Then the next sync overwrites their edit and nobody knows why. Remote-authoritative fields are read-only *because* the remote system wins; if users must edit, that field belongs in the local half, not the mapping. |
|
|
540
1508
|
| "I'll sync everything from the remote entity, just in case." | Every mapped field is personal data you now store, retain and must erase. Map what the application uses. |
|
|
541
1509
|
| "The cursor is null, so orphan reconciliation succeeded." | A fresh or retried first batch also has a null cursor. Check `reconciliationStatus`: unknown source identities skip reconciliation, while failed loads keep the previous checkpoint. |
|
|
1510
|
+
| "A timeout on a write probably failed — the client can just retry with a fresh key." | A timeout says nothing about whether the remote applied it. Retrying under a new key is the duplicate the required Idempotency-Key exists to prevent; read the row first. |
|
|
1511
|
+
| "I'll open every write verb now so the resource is ready later." | An opened verb with no operation is refused at startup, and one whose dialect cannot write refuses the whole application. Open what an operation performs, when it performs it. |
|
|
1512
|
+
| "Incremental passes read every change, so a nightly full pass is wasted work." | A deletion is not a change: no incremental read can see it. Without full passes a row deleted in the source stays in the destination forever — `fullPassCron` is required for exactly that reason. |
|
|
1513
|
+
| "I'll set the watermark from our clock when the run starts." | Your clock and the source's disagree, and the gap is rows nobody reads. The watermark is a position in the source's own `write_date` order, reached by rows actually LOADED, and the framework owns it. |
|
|
1514
|
+
| "I'll give the pipeline the whole instance budget so the sync finishes sooner." | A pipeline takes each slot the moment it frees, so an equal ceiling refuses every person's read for as long as a pass runs — and startup refuses it. The pass already finishes: it waits instead of failing, across runs if it must. |
|
|
1515
|
+
| "I'll map `parent_id` as a REMOTE_FIELD and join on the remote id later." | Then nothing in the framework treats it as a link — no picker, no nested read, no cascade — and every consumer re-derives the join. A `REMOTE_REFERENCE` writes a real foreign key to the local copy. |
|
|
1516
|
+
| "I'll add a `transform` function to the mapping entry for this one field." | Refused at startup: an unknown key on a mapping entry is an error, not an ignored option. Declare an expression, or derive the value in a pre-load step of your own code — never in code the declaration does not show. |
|
|
1517
|
+
| "An unmapped vendor code can fall back to some default member." | Only if every future code genuinely means that member. The default rejection is what makes a new vendor code visible on the next run instead of folding it silently into the wrong member. |
|
|
1518
|
+
| "I'll send new records to the ERP from an `afterCreate` hook." | A hook runs inside the user's write, so an ERP outage fails their save, a retry creates the record twice, and nothing records who changed what. An OUTBOUND pipeline sends later, under an idempotency key, with an audit row per write. |
|
|
542
1519
|
| "I'll bump the version to force a re-sync." | Unnecessary. A pipeline detects change by comparing remote values, not by a version. |
|
|
543
1520
|
|
|
544
1521
|
## Red Flags
|
|
@@ -549,9 +1526,30 @@ rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg 'z_file\(|ragSour
|
|
|
549
1526
|
overwrites whatever a user typed.
|
|
550
1527
|
- `population: CLOSED` alongside a create-shaped custom operation — refused at startup, and the
|
|
551
1528
|
message names the operation.
|
|
1529
|
+
- A run reporting rejected rows after the source added a selection value — an `ENUM_MAP` that does not
|
|
1530
|
+
map it; catch it with the declared-expressions grep above and map the code.
|
|
552
1531
|
- Concurrent pipeline execution across application instances — single-instance execution is required until destination mutations have exclusive ownership. Checkpoint conflicts alone do not fence deletion.
|
|
553
1532
|
- A binding whose `system` was copied from another resource without checking the instance is the one
|
|
554
1533
|
you meant — two instances of one vendor differ only by that name.
|
|
1534
|
+
- A bulk write or a `haveBulkOperation` twin on a virtual resource — the fourth grep; refused at
|
|
1535
|
+
startup, because N remote writes cannot roll back as one.
|
|
1536
|
+
- A client that retries `SYSTEM_OF_RECORD_WRITE_OUTCOME_UNKNOWN` under a NEW key — that is exactly the
|
|
1537
|
+
duplicate the Idempotency-Key exists to prevent; the first write may have landed.
|
|
1538
|
+
- An `incremental` pipeline whose `fullPassCron` runs rarely (monthly, yearly) — the fifth grep. Rows
|
|
1539
|
+
deleted in the source survive locally until it runs.
|
|
1540
|
+
- A pipeline whose run report shows `pacing.stoppedAtDeadline: true` on every run — the ceiling is too
|
|
1541
|
+
low for the population, or `maxRunDurationMs` too short; the pass still progresses by cursor, only
|
|
1542
|
+
slower. Catch the numbers with the rate-budget grep above.
|
|
1543
|
+
- A mapped remote id field (`parent_id`, `*_id`) declared as `REMOTE_FIELD` into a string column — the
|
|
1544
|
+
remote-reference grep above; it lands the remote id, not a link to the local copy.
|
|
1545
|
+
- A run whose `pendingReferences` never falls — the targets sit outside the `sourceFilter` or in an
|
|
1546
|
+
unassigned partition; the references will wait forever until the target is loaded.
|
|
1547
|
+
- A run reporting `liveSuppressedRows` above zero — an erasure did not hold; erase those rows again.
|
|
1548
|
+
(`suppressedRows` above zero is expected; never delete a suppression to "fix" it — that re-imports.)
|
|
1549
|
+
- An OUTBOUND pipeline whose runs show `waiting.awaitingOperator` above zero — creates of unknown outcome that
|
|
1550
|
+
nobody has answered and that are never sent again on their own; look each up in the system of record and answer
|
|
1551
|
+
it through `POST /internal/admin/external-data/outbound-changes/resolve`. Catch the declarations with the
|
|
1552
|
+
OUTBOUND grep above.
|
|
555
1553
|
- A `STANDALONE` primary-scope anchor on a virtual resource. It answers 403 `parent_scope_denied` to
|
|
556
1554
|
an organization owner, because the execution context's organization id comes from the URL and a
|
|
557
1555
|
standalone resource is not routed under its scope parent — measured, not inferred.
|