@wildo-ai/framework-knowledge 1.1.9 → 1.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
- package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
- package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +4 -2
- package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
- package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +9 -3
- 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 +84 -4
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/index.d.ts.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 +1 -1
- 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.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +39 -1
- 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 +132 -20
- 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.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
- 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 -6
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -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 +85 -8
- 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 +4 -3
- 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 +4 -3
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
- 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 +8 -4
- 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 +4 -1
- 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 +2 -1
- 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.map +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -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.map +1 -1
- package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +10 -4
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +5 -3
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +11 -9
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +17 -3
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +19 -2
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
- 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.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -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 +13 -5
- 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.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +38 -3
- 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 +2 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
- 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.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +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 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +1 -1
- 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 +149 -11
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +40 -2
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +55 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +10 -2
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +107 -11
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -2
- package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
- package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
- package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
- package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +2 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
- package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
- package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +7 -3
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +3 -3
- package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +56 -16
- package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +6 -4
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +30 -9
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +5 -3
- package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +12 -1
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
- package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
- package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +19 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +19 -1
- package/dist/knowledge/references/brand.name-choice.config.md +20 -3
- package/dist/knowledge/references/brand.name-screening.config.md +58 -3
- package/dist/knowledge/references/build-plan.task-graph.config.md +55 -0
- package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
- package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
- package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
- package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
- package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
- package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
- package/dist/knowledge/references/example.data-seeding.minimal.md +10 -9
- package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
- package/dist/knowledge/references/example.email.template.minimal.md +1 -1
- package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
- package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
- package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
- package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
- package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
- package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
- package/dist/knowledge/references/experience-plan.config.md +60 -7
- package/dist/knowledge/references/market.context-block.builder.md +1 -1
- package/dist/knowledge/references/placement-plan.config.md +43 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
- package/dist/knowledge/references/requirements.references.conventions.md +1 -1
- package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
- package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
- package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
- package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
- package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
- package/dist/knowledge/references/saas.backend.email.send.md +77 -0
- package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
- package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
- package/dist/knowledge/references/saas.data-seeding.definition-input.md +8 -2
- package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
- package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
- package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
- package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
- package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
- package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
- package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
- package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
- package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
- package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
- package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
- package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
- package/dist/knowledge/references/saas.website.astro.label-loader.md +3 -0
- package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
- package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
- package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
- package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
- package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
- package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
- package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
- package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
- package/dist/knowledge/references/website-plan.config.md +26 -0
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
- package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
- package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
- package/dist/knowledge/references/zod.factories.code.md +1 -0
- package/dist/knowledge/references/zod.factories.duration.md +1 -0
- package/dist/knowledge/references/zod.factories.money.md +1 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +337 -1
- package/dist/knowledge/registries/playbooks.json +18 -18
- package/dist/knowledge/registries/source-tags.json +1435 -873
- package/dist/knowledge/rules/live-context-door.md +1 -1
- package/dist/knowledge/skills/INDEX.md +3 -1
- package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
- package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
- package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
- package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
- package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
- package/dist/knowledge/skills/brand-name-screening/SKILL.md +33 -9
- package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +78 -6
- package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +30 -8
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +2 -1
- package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
- package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
- package/dist/knowledge/skills/config-saas/SKILL.md +25 -11
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +51 -1
- package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
- package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
- package/dist/knowledge/skills/email-add-template/SKILL.md +27 -5
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
- package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
- package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
- package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
- package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
- package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +18 -4
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
- package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +6 -1
- package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
- package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
- package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
- package/dist/knowledge/skills/market-category/SKILL.md +21 -7
- package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +11 -3
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +1 -1
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
- package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
- package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
- package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
- package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
- package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
- package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
- package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
- package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +14 -3
- package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
- package/dist/knowledge/skills/module-relationships/SKILL.md +31 -4
- package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
- package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
- package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
- package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
- package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
- package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
- package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
- package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
- package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
- package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
- package/dist/knowledge/skills/seeding-authoring/SKILL.md +155 -40
- package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
- package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +148 -4
- package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
- package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
- package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
- package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
- package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
- package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
- package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
- package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
- package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
- package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
- package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
- package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
- package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
- package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
- package/dist/knowledge/skills/website-factory-advanced/SKILL.md +10 -2
- package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
- package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
- package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
- package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
- package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
- package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
- package/dist/knowledge/skills/website-page-authoring/SKILL.md +16 -5
- package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
- package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-faq/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +10 -2
- package/dist/knowledge/skills/website-section-hero/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +12 -2
- package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +15 -3
- package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
- package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
- package/dist/knowledge/topic-index.json +1441 -269
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Framework — frontend resource UI contracts (saas-frontend-lib)
|
|
2
2
|
|
|
3
|
-
Source-backed excerpts for `OperationKey` / typed keys, per-operation frontend config, full `ResourceUIBehaviorConfig`, and the `ResourceUIBehavior` preset map.
|
|
3
|
+
Source-backed excerpts for `OperationKey` / typed keys, per-operation frontend config, full `ResourceUIBehaviorConfig`, the parameters a `getFrontendResourceLabel` function receives, and the `ResourceUIBehavior` preset map.
|
|
4
4
|
|
|
5
5
|
## Import Origins
|
|
6
6
|
|
|
@@ -116,6 +116,8 @@ export enum CollectionFilterPanelVisibility {
|
|
|
116
116
|
HIDDEN = 'hidden',
|
|
117
117
|
}
|
|
118
118
|
|
|
119
|
+
/**
|
|
120
|
+
*/
|
|
119
121
|
/**
|
|
120
122
|
* A DATE WINDOW named relative to NOW, for a preset filter that must mean the same thing tomorrow.
|
|
121
123
|
*
|
|
@@ -128,39 +130,63 @@ export enum CollectionFilterPanelVisibility {
|
|
|
128
130
|
* Resolution is in the VIEWER's timezone, which is the only one that makes "today" true for the
|
|
129
131
|
* person reading the screen. The backend compares instants, so the boundaries travel as absolute
|
|
130
132
|
* times and nothing downstream has to know a timezone was involved.
|
|
133
|
+
*
|
|
134
|
+
* Every window is whole local days and ends at the LAST instant of its last day, one millisecond before the next local
|
|
135
|
+
* midnight. The date-range filter's end bound is inclusive, and a date-only value (a due date picked in a calendar) is
|
|
136
|
+
* stored at the local midnight of the day it names, so ending at the next midnight would also match the day after.
|
|
131
137
|
*/
|
|
132
138
|
export enum CollectionFilterPresetRelativeRange {
|
|
133
|
-
/**
|
|
139
|
+
/** All of today, local: midnight this morning to the end of the day. */
|
|
134
140
|
TODAY = 'today',
|
|
135
|
-
/**
|
|
141
|
+
/** All of yesterday, local. */
|
|
136
142
|
YESTERDAY = 'yesterday',
|
|
137
143
|
/** The last seven days INCLUDING today — the rolling week, not the last seven whole days. */
|
|
138
144
|
LAST_7_DAYS = 'last_7_days',
|
|
139
145
|
/** The last thirty days including today. */
|
|
140
146
|
LAST_30_DAYS = 'last_30_days',
|
|
141
|
-
/** The first of this calendar month
|
|
147
|
+
/** The first of this calendar month through the end of today. */
|
|
142
148
|
THIS_MONTH = 'this_month',
|
|
143
|
-
/** The first of this calendar year
|
|
149
|
+
/** The first of this calendar year through the end of today. */
|
|
144
150
|
THIS_YEAR = 'this_year',
|
|
151
|
+
/**
|
|
152
|
+
* Everything BEFORE today, local: what an "overdue" list shows on a due-date field. Ends at the last instant of
|
|
153
|
+
* yesterday, so a date-only value due TODAY is due, not overdue. A deadline with a time earlier today is in TODAY, not
|
|
154
|
+
* here: the window is whole days, like every other member, so the pill reads the same all day.
|
|
155
|
+
*/
|
|
156
|
+
BEFORE_TODAY = 'before_today',
|
|
157
|
+
/** Today and the six days after it, local: "due this week" from today. */
|
|
158
|
+
NEXT_7_DAYS = 'next_7_days',
|
|
159
|
+
/** Today and the twenty-nine days after it, local. */
|
|
160
|
+
NEXT_30_DAYS = 'next_30_days',
|
|
145
161
|
}
|
|
146
162
|
|
|
147
163
|
/**
|
|
148
|
-
*
|
|
164
|
+
* A value a preset can only know once it is clicked, because it depends on WHO is looking. Resolved from the
|
|
165
|
+
* viewer's session at that moment, like a relative range is resolved from the clock, so "My jobs" means the person
|
|
166
|
+
* reading the list, whoever that is.
|
|
149
167
|
*
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
|
|
153
|
-
|
|
168
|
+
* A preset naming one is unavailable to a viewer the value cannot be resolved for (no signed-in user): the pill is
|
|
169
|
+
* disabled rather than applied without the field, which would show a different list under the same name.
|
|
170
|
+
*/
|
|
171
|
+
export enum CollectionFilterPresetContextValue {
|
|
172
|
+
/** The signed-in user's id, for a reference field such as an assignee or owner. */
|
|
173
|
+
CURRENT_USER = 'current_user',
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* What a preset ASSIGNS to one filter field.
|
|
154
178
|
*
|
|
155
|
-
*
|
|
156
|
-
* mean anything: the framework's collection filters carried a date range and scalars and no numeric
|
|
157
|
-
* range, so a preset could have declared "cost below 500" and nothing between here and the database
|
|
158
|
-
* would have honoured it. It is expressible now because `Resources_Filter_NumberRangeSchema`, the
|
|
159
|
-
* controller's fail-closed value guard and the cross-adapter normalizer all learned the `{ min, max }`
|
|
160
|
-
* vocabulary — a preset assigning one is writing the same value the filter panel's own two inputs do.
|
|
179
|
+
* Four kinds, split by WHEN the value is known:
|
|
161
180
|
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
181
|
+
* - a LITERAL (string, number, boolean) is fixed at authoring time and covers every enum value, id, number and flag,
|
|
182
|
+
* which is the whole of "filter to HIGH priority";
|
|
183
|
+
* - a RELATIVE RANGE (`{ relativeRange }`) is the temporal case, resolved when the pill is clicked, because an authored
|
|
184
|
+
* answer would be wrong by tomorrow;
|
|
185
|
+
* - a NUMERIC BOUND (`{ min?, max? }`) writes the same value the filter panel's own two number inputs do, and the
|
|
186
|
+
* backend applies it on every adapter. Both bounds are optional because "under 500" has no floor, and that is the
|
|
187
|
+
* commonest threshold anyone asks for;
|
|
188
|
+
* - a CONTEXT VALUE (`{ contextValue }`) is known only from who is looking, such as "assigned to me", and is resolved
|
|
189
|
+
* when the pill is clicked, so the same authored preset shows each viewer their own rows.
|
|
164
190
|
*/
|
|
165
191
|
export const CollectionFilterPresetValueSchema = z.union([
|
|
166
192
|
z.string(),
|
|
@@ -168,6 +194,7 @@ export const CollectionFilterPresetValueSchema = z.union([
|
|
|
168
194
|
z.boolean(),
|
|
169
195
|
z.object({ relativeRange: z.enum(CollectionFilterPresetRelativeRange) }),
|
|
170
196
|
z.object({ min: z.number().optional(), max: z.number().optional() }),
|
|
197
|
+
z.object({ contextValue: z.enum(CollectionFilterPresetContextValue) }),
|
|
171
198
|
]);
|
|
172
199
|
export type CollectionFilterPresetValue = z.infer<typeof CollectionFilterPresetValueSchema>;
|
|
173
200
|
|
|
@@ -731,6 +758,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
731
758
|
* presetFilters: [
|
|
732
759
|
* { ref: 'urgent', filters: { priority: 'high' } },
|
|
733
760
|
* { ref: 'created-today', filters: { createdAt: { relativeRange: CollectionFilterPresetRelativeRange.TODAY } } },
|
|
761
|
+
* { ref: 'overdue', filters: { dueAt: { relativeRange: CollectionFilterPresetRelativeRange.BEFORE_TODAY }, status: 'open' } },
|
|
762
|
+
* { ref: 'mine', filters: { assigneeUserId: { contextValue: CollectionFilterPresetContextValue.CURRENT_USER } } },
|
|
734
763
|
* ]
|
|
735
764
|
*/
|
|
736
765
|
presetFilters: z.array(CollectionFilterPresetSchema).optional(),
|
|
@@ -1033,7 +1062,10 @@ export type ResourceUIBehaviorConfig<
|
|
|
1033
1062
|
* Can be either:
|
|
1034
1063
|
* - `string[]` — array of field paths to concatenate (each entry is a field
|
|
1035
1064
|
* name on the summary record, including any server-resolved virtual field
|
|
1036
|
-
* such as a `forwardedLabel`, e.g. `['instanceLabel']`).
|
|
1065
|
+
* such as a `forwardedLabel`, e.g. `['instanceLabel']`). The present,
|
|
1066
|
+
* non-empty values are trimmed and joined with ONE SPACE (`['firstName',
|
|
1067
|
+
* 'lastName']` → "Ada Lovelace"); for any other separator, or for words,
|
|
1068
|
+
* use the function form.
|
|
1037
1069
|
* - `(params: ResourceUIBehaviorLabelParams) => string` — a function
|
|
1038
1070
|
*
|
|
1039
1071
|
* Used by `ResourceListItemRenderer` (rows) and `ResourceLayout_Header` (titles).
|
|
@@ -1134,6 +1166,56 @@ export type ResourceUIBehaviorConfig<
|
|
|
1134
1166
|
|
|
1135
1167
|
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
1136
1168
|
|
|
1169
|
+
```typescript
|
|
1170
|
+
*
|
|
1171
|
+
* Parameters passed to a `getFrontendResourceLabel` function: what a resource's ui-behavior receives when it names one
|
|
1172
|
+
* record (a list row, a page title, a reference chip). Import the type from `@wildo-ai/saas-frontend-lib`.
|
|
1173
|
+
*
|
|
1174
|
+
* Words in a label come from `t`, which takes a FULL key (`resources.<type>.…`). This resource's own `resources.<type>`
|
|
1175
|
+
* words are always loaded; a label that also needs words from ANOTHER label section declares it in
|
|
1176
|
+
* `instanceLabelSections`, or `t` renders the key itself wherever that section has not been loaded. Dates go through
|
|
1177
|
+
* `formatDate` / `formatDateTime`, never a hand-formatted string.
|
|
1178
|
+
*
|
|
1179
|
+
* Generic `TMainSchema` defaults to `z.ZodAny` — presets and records use the
|
|
1180
|
+
* default (giving `currentObject: any`), while app-level configs can narrow it
|
|
1181
|
+
* to a concrete schema for type-safe field access.
|
|
1182
|
+
*
|
|
1183
|
+
* @example
|
|
1184
|
+
* // An invoice named by its number and its issue date, in the viewer's date format.
|
|
1185
|
+
* getFrontendResourceLabel: ({ currentObject, formatDate }) => `${currentObject.number} · ${formatDate(currentObject.issuedAt)}`,
|
|
1186
|
+
*/
|
|
1187
|
+
export type ResourceUIBehaviorLabelParams<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
|
|
1188
|
+
currentObject: z.infer<TMainSchema>;
|
|
1189
|
+
objectContext: any;
|
|
1190
|
+
initiatorUserContext?: any;
|
|
1191
|
+
t: (toTranslate: string, params?: Record<string, any>) => string;
|
|
1192
|
+
/**
|
|
1193
|
+
* Formats a date the way the viewer's regional preferences (date format, timezone) render one everywhere
|
|
1194
|
+
* else. A label built from a date must use it: a hand-formatted `YYYY-MM-DD` agreed with the record's own
|
|
1195
|
+
* card only for a viewer whose preference happened to be ISO, and a different timezone could shift the day.
|
|
1196
|
+
*/
|
|
1197
|
+
formatDate: (value: Date | string | number) => string;
|
|
1198
|
+
/**
|
|
1199
|
+
* `formatDate` with the time of day, for a record whose name is an instant rather than a day — an audit
|
|
1200
|
+
* event, where many share a date and only the time tells them apart.
|
|
1201
|
+
*/
|
|
1202
|
+
formatDateTime: (value: Date | string | number) => string;
|
|
1203
|
+
/**
|
|
1204
|
+
* The resource being named. One polymorphic behavior serves several resource types (an organization's and a
|
|
1205
|
+
* user's billing account share one callback), and a record with no name of its own is named by ITS resource's
|
|
1206
|
+
* words — which only the resource type can address in the label tree.
|
|
1207
|
+
*/
|
|
1208
|
+
resourceType: string;
|
|
1209
|
+
};
|
|
1210
|
+
```
|
|
1211
|
+
## Import Origins
|
|
1212
|
+
|
|
1213
|
+
- `@wildo-ai/saas-frontend-lib`
|
|
1214
|
+
|
|
1215
|
+
## Source Excerpts
|
|
1216
|
+
|
|
1217
|
+
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
1218
|
+
|
|
1137
1219
|
```typescript
|
|
1138
1220
|
*
|
|
1139
1221
|
* Complete frontend resource configuration preset for an application.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: seeding-authoring
|
|
3
|
-
description: Author a `DataSeedDefinition` end-to-end — pick the right Level (A vs B), pick the right mode (LAZY / ADDITIVE / UPGRADE / SYNC) for the row's re-run semantics, declare a stable business key on the resource schema, declare which fields the seed *owns* via `managedFields`, and (for UPGRADE) ship a migrator + rename ledger so business-key relocations preserve identity. Use when the user says "seed system email templates", "give every new organization a default workspace", "add a default dashboard the first time a user opens the dashboards list", "ship a closed enum as DB rows synced from the declaration", "deploy version 2 of the welcome template without losing user customization", or any request that produces a new `createDataSeedDefinition({...})` call site.
|
|
3
|
+
description: Author a `DataSeedDefinition` end-to-end — pick the right Level (A vs B), pick the right mode (LAZY / ADDITIVE / UPGRADE / SYNC) for the row's re-run semantics, declare a stable business key on the resource schema, declare which fields the seed *owns* via `managedFields`, and (for UPGRADE) ship a migrator + rename ledger so business-key relocations preserve identity. Use when the user says "seed system email templates", "give every new organization a default workspace", "add a default dashboard the first time a user opens the dashboards list", "ship a closed enum as DB rows synced from the declaration", "deploy version 2 of the welcome template without losing user customization", "link the demo contacts to the demo customers", or any request that produces a new `createDataSeedDefinition({...})` call site.
|
|
4
4
|
user-invocable: false
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -26,7 +26,7 @@ into the application's database. One factory entry point
|
|
|
26
26
|
(`createDataSeedDefinition`) drives every seed; the authoring decisions
|
|
27
27
|
live entirely in its single input object.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Seven decisions, ordered by blast-radius:
|
|
30
30
|
|
|
31
31
|
1. **Level (A vs B)** — does this seed fire from an *application
|
|
32
32
|
lifecycle* event (boot, version upgrade, scheduled refresh,
|
|
@@ -46,6 +46,8 @@ Five decisions, ordered by blast-radius:
|
|
|
46
46
|
5. **Rename ledger** — when a business-key value changes at the
|
|
47
47
|
declaration site, ship a `renames[]` entry so the next pass
|
|
48
48
|
relocates existing rows instead of orphaning them.
|
|
49
|
+
6. **Where may the rows exist?** — demonstration data never in production.
|
|
50
|
+
7. **Links to another seed's rows** — `referenceDataSeedRow(...)`, with that seed in `dependsOn`.
|
|
49
51
|
|
|
50
52
|
The framework rejects almost every authoring mistake at
|
|
51
53
|
`createDataSeedDefinition(...)` invocation time: missing `onOrphan`
|
|
@@ -94,7 +96,7 @@ metrics, `DataSeedRun` ledger queries) is covered by
|
|
|
94
96
|
- Adding `__seed` overlay to user-authored data (non-seed) → the
|
|
95
97
|
overlay is dispatcher-managed; never write it from app code
|
|
96
98
|
|
|
97
|
-
## The
|
|
99
|
+
## The Seven Authoring Decisions
|
|
98
100
|
|
|
99
101
|
### Decision 1: Level — A vs B
|
|
100
102
|
|
|
@@ -121,6 +123,17 @@ specific resource row. The triggering row's `_id` is the natural
|
|
|
121
123
|
> is a resource, not a deployment event). The same applies to any
|
|
122
124
|
> "on creation of resource X" pattern.
|
|
123
125
|
|
|
126
|
+
On any level, a per-scope seed keeps STATIC entries with `anchorEntriesToScopeForeignKey: true`:
|
|
127
|
+
leave the scope key (`organizationId`, …) out of the business key and the engine adds the id of the
|
|
128
|
+
scope row being seeded. Use a computed `entry()` only when VALUES depend on the triggering row. It returns
|
|
129
|
+
exactly one entry per call and has no way to skip a row: a row that should exist only when a condition holds is
|
|
130
|
+
created by an operation, not a seed.
|
|
131
|
+
|
|
132
|
+
**A seed write runs none of the resource's operation pipeline.** The engines write through the repository, so no
|
|
133
|
+
custom-implementation prefix or postfix runs, no `userNotifications` email is sent, and no operation audit row is
|
|
134
|
+
written; the run itself is recorded in the `DataSeedRun` ledger. So an entry carries every value a prefix would have
|
|
135
|
+
computed (a server-owned total, a derived status) itself, and a seeded row announces nothing to anyone.
|
|
136
|
+
|
|
124
137
|
### Decision 2: Mode — pick by re-run semantics
|
|
125
138
|
|
|
126
139
|
| Mode | Re-run safe? | Touches existing rows? | Required fields | Pick when … |
|
|
@@ -177,9 +190,8 @@ Behavioral effects:
|
|
|
177
190
|
- The seed's `entries[*].businessKey` is matched against this shape
|
|
178
191
|
(single field → object with one key; composite → object with all
|
|
179
192
|
keys present).
|
|
180
|
-
-
|
|
181
|
-
|
|
182
|
-
keys (the DB still references `_id`, immutable).
|
|
193
|
+
- `dependsOn[]` only ORDERS seeds. A link to another seed's row is a `referenceDataSeedRow` by THIS
|
|
194
|
+
business key (Decision 7); it stores the `_id`, and a reference still using a renamed key fails.
|
|
183
195
|
|
|
184
196
|
### Decision 4: Managed fields — what the seed *owns*
|
|
185
197
|
|
|
@@ -204,23 +216,7 @@ The dispatcher writes a `__seed` overlay onto each row recording
|
|
|
204
216
|
which fields it owns and which version owned them — this is the
|
|
205
217
|
runtime side of the contract; authors only declare `managedFields[]`.
|
|
206
218
|
|
|
207
|
-
|
|
208
|
-
> close-out): the `__seed` overlay tracks **`managedSince`**
|
|
209
|
-
> (the wall-clock `Date` at which the framework first stamped
|
|
210
|
-
> the row — preserved across subsequent passes by
|
|
211
|
-
> `buildDataSeedRowMetadataForUpsert`, and only re-set when the
|
|
212
|
-
> row is created). It does NOT carry `mode`, `runId`, or
|
|
213
|
-
> `seededAt` — earlier drafts
|
|
214
|
-
> of this guide and some forum discussions referenced those
|
|
215
|
-
> names as if they were persisted on the row. They are NOT:
|
|
216
|
-
> `mode` lives on the seed definition (not the row), `runId`
|
|
217
|
-
> lives on `DataSeedRun` (one row per pass, not per seeded
|
|
218
|
-
> document), and `seededAt` was renamed to `managedSince`
|
|
219
|
-
> early in the design to clarify the "first-stamp wall-clock"
|
|
220
|
-
> semantic. Authors should never need to read or write any of
|
|
221
|
-
> these — the overlay is dispatcher-private — but the naming
|
|
222
|
-
> matters for tests and for the `data-seed-row-metadata.shared.schemas.ts`
|
|
223
|
-
> source file.
|
|
219
|
+
The overlay's field names (`managedSince`; no `mode`, `runId` or `seededAt`): `references/seed-row-overlay.md`.
|
|
224
220
|
|
|
225
221
|
### Decision 5: Rename ledger — preserve identity across business-key changes
|
|
226
222
|
|
|
@@ -259,9 +255,25 @@ Factory-time invariants (rejected with actionable errors):
|
|
|
259
255
|
A restricted seed is withheld at registration in every other environment, so no trigger, schedule
|
|
260
256
|
or manual run reaches it there, and it is withheld when the deployment declares no environment at
|
|
261
257
|
all. Never mix the two kinds in one seed: the restriction applies to every row the seed writes.
|
|
262
|
-
For demonstration data, `ADDITIVE`
|
|
263
|
-
|
|
264
|
-
|
|
258
|
+
For demonstration data, `ADDITIVE` with `existingRowTreatment: FILL_MISSING_DEFAULTS` is the usual
|
|
259
|
+
shape — people edit sample rows while trying the application, and the default treatment would
|
|
260
|
+
re-stamp them on every pass. Pick the trigger by where the resource lives: an application-wide
|
|
261
|
+
resource seeds at `ON_APP_INIT` (`APPLICATION` scope); a resource that carries `organizationId`
|
|
262
|
+
seeds per organization on the `organizations` `afterCreate` trigger (`ORGANIZATION` scope), with
|
|
263
|
+
`anchorEntriesToScopeForeignKey: true` so each organization gets its own rows. Sample rows that
|
|
264
|
+
point at each other (a contact's customer, a quote's customer) use Decision 7.
|
|
265
|
+
`RuntimeEnvironment` comes from `@wildo-ai/saas-models`.
|
|
266
|
+
|
|
267
|
+
### Decision 7: Rows that point at another seed's rows — `referenceDataSeedRow`
|
|
268
|
+
|
|
269
|
+
`dependsOn` orders seeds and passes nothing, the engine generates `_id`, and a computed `entry()`
|
|
270
|
+
cannot read rows. So a foreign key to a row another seed writes is a REFERENCE —
|
|
271
|
+
`customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana@example.com' })` — which the
|
|
272
|
+
engine resolves to that row's `_id` before writing. List the referenced seed in `dependsOn` (the
|
|
273
|
+
factory refuses a static reference that is not). Nothing is ever written with a null or placeholder
|
|
274
|
+
key: an unresolved reference in `data` fails that entry, one in `businessKey` fails the whole run.
|
|
275
|
+
Read `references/cross-seed-row-references.md` (scope fill-in, environments, cross-tenant refusal)
|
|
276
|
+
before writing one.
|
|
265
277
|
|
|
266
278
|
## Workflow
|
|
267
279
|
|
|
@@ -361,7 +373,7 @@ import {
|
|
|
361
373
|
DataSeedResourceLifecyclePhase,
|
|
362
374
|
DataSeedScopeKind,
|
|
363
375
|
DataSeedTriggerKind,
|
|
364
|
-
} from '
|
|
376
|
+
} from '@wildo-ai/saas-backend-lib/data-seeding-models';
|
|
365
377
|
|
|
366
378
|
// ─────────────────────────────────────────────────────────────────────
|
|
367
379
|
// Level-A example — UPGRADE on app version upgrade.
|
|
@@ -419,7 +431,11 @@ const systemEmailTemplatesSeed = createDataSeedDefinition({
|
|
|
419
431
|
// Level-B example — ADDITIVE on Organization afterCreate.
|
|
420
432
|
// "When an Organization is created, spawn its default Workspace once."
|
|
421
433
|
// Computed `entry` lets the seed read the triggering row's `_id` and
|
|
422
|
-
// the audit `triggeredByUserId` for attribution.
|
|
434
|
+
// the audit `triggeredByUserId` for attribution. The organization's id
|
|
435
|
+
// goes in the BUSINESS KEY: every organization has its own default
|
|
436
|
+
// workspace, so the organization is part of that row's identity (a key
|
|
437
|
+
// of `workspaceKey` alone would make every organization share one row).
|
|
438
|
+
// ADDITIVE is safe to
|
|
423
439
|
// re-run: the dispatcher inspects `DataSeedRun` keyed on
|
|
424
440
|
// `(seedKey, scopeKind, relatedId)` and skips on COMPLETED.
|
|
425
441
|
//
|
|
@@ -431,15 +447,12 @@ const systemEmailTemplatesSeed = createDataSeedDefinition({
|
|
|
431
447
|
// ─────────────────────────────────────────────────────────────────────
|
|
432
448
|
const organizationDefaultWorkspaceSeed = createDataSeedDefinition({
|
|
433
449
|
seedKey: 'tasks-manager:org-default-workspace',
|
|
434
|
-
scope: {
|
|
435
|
-
kind: DataSeedScopeKind.CUSTOM,
|
|
436
|
-
relatedResourceType: 'organization',
|
|
437
|
-
},
|
|
450
|
+
scope: { kind: DataSeedScopeKind.ORGANIZATION },
|
|
438
451
|
resourceType: 'workspace',
|
|
439
452
|
triggers: [
|
|
440
453
|
{
|
|
441
454
|
triggerKind: DataSeedTriggerKind.RESOURCE_LIFECYCLE,
|
|
442
|
-
resourceType: '
|
|
455
|
+
resourceType: 'organizations',
|
|
443
456
|
phase: DataSeedResourceLifecyclePhase.AFTER_CREATE,
|
|
444
457
|
},
|
|
445
458
|
],
|
|
@@ -452,9 +465,9 @@ const organizationDefaultWorkspaceSeed = createDataSeedDefinition({
|
|
|
452
465
|
// DOES project through it, and rejects an empty list) or `SYNC`. See
|
|
453
466
|
// the `DataSeedMode` JSDoc for the full mode-by-mode contract.
|
|
454
467
|
entry: ({ triggeringRow, executionContext }) => ({
|
|
455
|
-
|
|
468
|
+
// The workspace resource declares `businessKeySet(['organizationId', 'workspaceKey'])`.
|
|
469
|
+
businessKey: { organizationId: triggeringRow?._id, workspaceKey: 'default' },
|
|
456
470
|
data: {
|
|
457
|
-
organizationId: triggeringRow?._id,
|
|
458
471
|
name: 'My Workspace',
|
|
459
472
|
ownerId: executionContext.triggeredByUserId,
|
|
460
473
|
},
|
|
@@ -490,6 +503,91 @@ const demoCustomersSeed = createDataSeedDefinition({
|
|
|
490
503
|
export { demoCustomersSeed, organizationDefaultWorkspaceSeed, systemEmailTemplatesSeed };
|
|
491
504
|
```
|
|
492
505
|
|
|
506
|
+
Demonstration rows that point at each other (Decision 7) — per-organization demo customers, and
|
|
507
|
+
demo contacts each linked to one of them:
|
|
508
|
+
|
|
509
|
+
|
|
510
|
+
## Usage Example
|
|
511
|
+
|
|
512
|
+
```typescript
|
|
513
|
+
import { RuntimeEnvironment } from '@wildo-ai/saas-models';
|
|
514
|
+
import {
|
|
515
|
+
createDataSeedDefinition,
|
|
516
|
+
DataSeedExistingRowTreatment,
|
|
517
|
+
DataSeedMode,
|
|
518
|
+
DataSeedResourceLifecyclePhase,
|
|
519
|
+
DataSeedScopeKind,
|
|
520
|
+
DataSeedTriggerKind,
|
|
521
|
+
referenceDataSeedRow,
|
|
522
|
+
type DataSeedTrigger,
|
|
523
|
+
} from '@wildo-ai/saas-backend-lib/data-seeding-models';
|
|
524
|
+
|
|
525
|
+
// Every new organization gets its own sample rows; production never gets any.
|
|
526
|
+
const ON_ORGANIZATION_CREATED: DataSeedTrigger[] = [{
|
|
527
|
+
triggerKind: DataSeedTriggerKind.RESOURCE_LIFECYCLE,
|
|
528
|
+
resourceType: 'organizations',
|
|
529
|
+
phase: DataSeedResourceLifecyclePhase.AFTER_CREATE,
|
|
530
|
+
}];
|
|
531
|
+
const DEMONSTRATION_ONLY = [RuntimeEnvironment.DEVELOPMENT, RuntimeEnvironment.STAGING];
|
|
532
|
+
|
|
533
|
+
// ─────────────────────────────────────────────────────────────────────
|
|
534
|
+
// The referenced seed. Its resource's business key is
|
|
535
|
+
// `businessKeySet(['organizationId', 'email'])`; the entries name only
|
|
536
|
+
// `email`, and `anchorEntriesToScopeForeignKey` adds the organization.
|
|
537
|
+
// ─────────────────────────────────────────────────────────────────────
|
|
538
|
+
const demoCustomersSeed = createDataSeedDefinition({
|
|
539
|
+
seedKey: 'crm:demo-customers',
|
|
540
|
+
scope: { kind: DataSeedScopeKind.ORGANIZATION },
|
|
541
|
+
resourceType: 'customers',
|
|
542
|
+
triggers: ON_ORGANIZATION_CREATED,
|
|
543
|
+
mode: DataSeedMode.ADDITIVE,
|
|
544
|
+
version: 1,
|
|
545
|
+
existingRowTreatment: DataSeedExistingRowTreatment.FILL_MISSING_DEFAULTS,
|
|
546
|
+
allowedApplicationEnvironments: DEMONSTRATION_ONLY,
|
|
547
|
+
anchorEntriesToScopeForeignKey: true,
|
|
548
|
+
entries: [
|
|
549
|
+
{ businessKey: { email: 'ana.martin@example.com' }, data: { name: 'Ana Martin' } },
|
|
550
|
+
{ businessKey: { email: 'office@becker.example.com' }, data: { name: 'Becker Hausverwaltung GmbH' } },
|
|
551
|
+
],
|
|
552
|
+
});
|
|
553
|
+
|
|
554
|
+
// ─────────────────────────────────────────────────────────────────────
|
|
555
|
+
// The referring seed. `customerId` is a REFERENCE, not a value: the
|
|
556
|
+
// engine replaces it with the customer row's `_id` before writing. The
|
|
557
|
+
// reference omits `organizationId` — both seeds are ORGANIZATION-scoped,
|
|
558
|
+
// so the engine fills in the organization being seeded. A contact whose
|
|
559
|
+
// customer row does not exist is reported on the run and not written.
|
|
560
|
+
// ─────────────────────────────────────────────────────────────────────
|
|
561
|
+
const demoContactsSeed = createDataSeedDefinition({
|
|
562
|
+
seedKey: 'crm:demo-contacts',
|
|
563
|
+
scope: { kind: DataSeedScopeKind.ORGANIZATION },
|
|
564
|
+
resourceType: 'contacts',
|
|
565
|
+
triggers: ON_ORGANIZATION_CREATED,
|
|
566
|
+
mode: DataSeedMode.ADDITIVE,
|
|
567
|
+
version: 1,
|
|
568
|
+
existingRowTreatment: DataSeedExistingRowTreatment.FILL_MISSING_DEFAULTS,
|
|
569
|
+
allowedApplicationEnvironments: DEMONSTRATION_ONLY,
|
|
570
|
+
anchorEntriesToScopeForeignKey: true,
|
|
571
|
+
// Required for every seed an entry references: it is what runs the customers first.
|
|
572
|
+
dependsOn: [{ seedKey: demoCustomersSeed.seedKey }],
|
|
573
|
+
entries: [
|
|
574
|
+
{
|
|
575
|
+
businessKey: { email: 'ana@martin.example.com' },
|
|
576
|
+
data: { firstName: 'Ana', customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana.martin@example.com' }) },
|
|
577
|
+
},
|
|
578
|
+
{
|
|
579
|
+
businessKey: { email: 'jonas.becker@becker.example.com' },
|
|
580
|
+
data: { firstName: 'Jonas', customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'office@becker.example.com' }) },
|
|
581
|
+
},
|
|
582
|
+
],
|
|
583
|
+
});
|
|
584
|
+
|
|
585
|
+
export { demoContactsSeed, demoCustomersSeed };
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
The contact seed lists the customer seed in `dependsOn` and references customers by `email` only:
|
|
589
|
+
both seeds are `ORGANIZATION`-scoped, so the engine adds the organization being seeded.
|
|
590
|
+
|
|
493
591
|
What earns its place in this block:
|
|
494
592
|
|
|
495
593
|
- **Stable `seedKey` with module prefix** —
|
|
@@ -497,10 +595,9 @@ What earns its place in this block:
|
|
|
497
595
|
`'tasks-manager:org-default-workspace'`. The colon segments are
|
|
498
596
|
convention; the dispatcher only requires non-empty.
|
|
499
597
|
- **Explicit `scope`** discriminated by `kind`. Level-A seeds for
|
|
500
|
-
per-application data use `APPLICATION
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
pass per Organization row.
|
|
598
|
+
per-application data use `APPLICATION`; the Level-B organization seed
|
|
599
|
+
uses `ORGANIZATION` on the `organizations` trigger, and keys its row by
|
|
600
|
+
the organization so each one gets its own.
|
|
504
601
|
- **Mode-appropriate fields**: UPGRADE ships `managedFields` +
|
|
505
602
|
`migrators.fromVersion[1]` + `renames`. ADDITIVE has no
|
|
506
603
|
`managedFields` because the writer bypasses that projection on
|
|
@@ -537,6 +634,10 @@ What is **not** in this block (and shouldn't be):
|
|
|
537
634
|
- `references/framework-data-seeding-api.md` — `DataSeedMode` enum +
|
|
538
635
|
`DataSeedDefinitionInput` interface (the canonical authoring
|
|
539
636
|
surface — what every field means, what's required for each mode)
|
|
637
|
+
- `references/cross-seed-row-references.md` — every rule of
|
|
638
|
+
`referenceDataSeedRow` (Decision 7): ordering, scope fill-in, failure
|
|
639
|
+
classes, what is not supported
|
|
640
|
+
- `references/seed-row-overlay.md` — the `__seed` overlay's field names
|
|
540
641
|
- `references/data-seeding-mode-picker.md` — extended decision tree
|
|
541
642
|
for Decision 2 (mode picker) with worked failure modes for each
|
|
542
643
|
mode
|
|
@@ -554,6 +655,7 @@ What is **not** in this block (and shouldn't be):
|
|
|
554
655
|
- [ ] `renames[*].field` is a business-key field on the resource
|
|
555
656
|
- [ ] `renames[*].to` matches a declared `entries[*].businessKey[field]`
|
|
556
657
|
- [ ] A demonstration seed declares `allowedApplicationEnvironments` without `production`; a reference seed omits it
|
|
658
|
+
- [ ] A foreign key to another seed's row is a `referenceDataSeedRow(...)` (never unset or a placeholder) and that seed is in `dependsOn`
|
|
557
659
|
- [ ] Seed surfaced on the module's `BackendDomainModule.seeds?: DataSeedDefinition[]` slot
|
|
558
660
|
(aggregated by `mergeBackendDomainModules` and threaded into the assembly's `dataSeeds`)
|
|
559
661
|
|
|
@@ -566,10 +668,19 @@ Run from the app root, substituting `<module>` and `<seed-key>`:
|
|
|
566
668
|
| Seed file uses `createDataSeedDefinition` | `rg -n 'createDataSeedDefinition' backend-api/src/modules/<module>/` |
|
|
567
669
|
| Seed file imports the factory from the focused subpath | `rg -n "from '@wildo-ai/saas-backend-lib/data-seeding-models'" backend-api/src/modules/<module>/` |
|
|
568
670
|
| Seed file does NOT import from the package root | `rg -n "from '@wildo-ai/saas-backend-lib'" backend-api/src/modules/<module>/seeds/` (must be empty for seed files) |
|
|
569
|
-
| Resource schema declares a business key |
|
|
671
|
+
| Resource schema declares a business key | see the commands below the table |
|
|
570
672
|
| Module record wires `seeds` | `rg -n '\bseeds\s*:' backend-api/src/modules/<module>/index.ts` |
|
|
673
|
+
| A seed using references lists its `dependsOn` | see the commands below the table (must be empty) |
|
|
571
674
|
| Demonstration seeds are kept out of production | `rg --files-without-match 'allowedApplicationEnvironments' backend-api/src/modules/<module>/seeds/*demo*.seed.ts` (must be empty); `rg -n 'RuntimeEnvironment.PRODUCTION' backend-api/src/modules/<module>/seeds/*demo*.seed.ts` (must be empty) |
|
|
572
675
|
|
|
676
|
+
```bash
|
|
677
|
+
# Resource schema declares a business key
|
|
678
|
+
rg -n 'isBusinessKey\(\)|businessKeySet\(' shared-lib/src/modules/<module>/resources/<resource>/<resource>.schemas.ts
|
|
679
|
+
|
|
680
|
+
# A seed using references lists its `dependsOn`
|
|
681
|
+
rg -l 'referenceDataSeedRow' backend-api/src/modules/<module>/seeds/ | xargs rg --files-without-match 'dependsOn'
|
|
682
|
+
```
|
|
683
|
+
|
|
573
684
|
The high-signal invariants are **"resource schema declares a
|
|
574
685
|
business key"** combined with **"seed file uses
|
|
575
686
|
`createDataSeedDefinition`"** — without the schema marker, the
|
|
@@ -585,6 +696,8 @@ with an actionable error.
|
|
|
585
696
|
| "I'll declare `triggers` AND `lazyAccess` to be safe" | Factory rejects (Phase 5 audit F-2/F-12/F-18: single declaration site). The auto-injection is the contract; double-declaring just creates divergence surface. |
|
|
586
697
|
| "I'll default `onOrphan: REPORT` for SYNC" | The framework refuses to default destructive policies (D3). Each option (`DELETE` / `DEPRECATE` / `REPORT`) has a different operational blast-radius; the developer must pick deliberately per seed. |
|
|
587
698
|
| "I'll rename the resource field directly without a `renames` entry" | Without the rename ledger, the next pass inserts a duplicate at the new business-key value and orphans the existing row (SYNC) or leaves it unowned (UPGRADE / ADDITIVE). Always ship the ledger entry in the same commit as the value change. |
|
|
699
|
+
| "The contact seed can't know the customer's `_id`, so I'll leave `customerId` unset" | Use `referenceDataSeedRow(customersSeed, { …businessKey })` and list the customer seed in `dependsOn`: the engine resolves it to the row's `_id`. An unset or placeholder foreign key is a demo that shows unlinked records. |
|
|
700
|
+
| "`dependsOn` resolves the link for me" | `dependsOn` only orders the seeds. Without a `referenceDataSeedRow` value nothing writes the foreign key. |
|
|
588
701
|
| "I don't need `version` to bump for this UPGRADE" | UPGRADE re-applies `managedFields` only when `seedVersion < declared` — without bumping, existing rows skip the upgrade. Bump per material change. |
|
|
589
702
|
|
|
590
703
|
## Red Flags
|
|
@@ -610,6 +723,8 @@ with an actionable error.
|
|
|
610
723
|
production (its sample rows land beside real ones; catch with the demonstration-seed grep above)
|
|
611
724
|
- `schedule.cron` declared on a LAZY seed (factory rejects — LAZY's
|
|
612
725
|
contract is "first access creates the row, never re-applied")
|
|
726
|
+
- A demo seed whose foreign key to another seeded row is unset, `null` or hard-coded (Decision 7)
|
|
727
|
+
- `referenceDataSeedRow` in a seed without `dependsOn` (catch with the references grep above)
|
|
613
728
|
|
|
614
729
|
## Related Skills
|
|
615
730
|
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Cross-seed row references — `referenceDataSeedRow`
|
|
2
|
+
|
|
3
|
+
Read this before a seed writes a foreign key to a row ANOTHER seed creates: a demonstration contact's
|
|
4
|
+
customer, a quote's customer, an invoice's job, a catalog item's category.
|
|
5
|
+
|
|
6
|
+
## Why a reference, and not a value
|
|
7
|
+
|
|
8
|
+
The engine generates every seeded row's `_id`, so no seed can write another seed's row id as a
|
|
9
|
+
literal. `dependsOn` only ORDERS seeds — it passes no data — and a computed `entry()` receives the
|
|
10
|
+
triggering row and nothing else; it cannot look rows up. A reference is the one way to say "the
|
|
11
|
+
`_id` of THAT row":
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana.martin@example.com' })
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The first argument is the target seed's DEFINITION (import it from the module that declares it), so
|
|
18
|
+
a typo is a compile error. The second is the target row's business key, as the target resource
|
|
19
|
+
declares it (`isBusinessKey()` / `businessKeySet([...])`). The engine replaces the reference with the
|
|
20
|
+
row's `_id` before the seed writes anything.
|
|
21
|
+
|
|
22
|
+
## The rules
|
|
23
|
+
|
|
24
|
+
| # | Rule | Enforced by |
|
|
25
|
+
|---|------|-------------|
|
|
26
|
+
| 1 | The referenced seed is listed in the referring seed's `dependsOn`. That edge is what runs it first. | `createDataSeedDefinition` refuses a static entry; a computed `entry()` fails its run with a CONFIGURATION error |
|
|
27
|
+
| 2 | A seed referencing a seed restricted by `allowedApplicationEnvironments` (a demonstration seed) is restricted to environments that seed runs in. Elsewhere the referenced seed is withheld and its rows never exist. | `createDataSeedDefinition` (static) and the engine (computed) |
|
|
28
|
+
| 3 | A seed never references its own entries. References resolve before the seed writes, so its own rows are not there yet. Split the rows into two seeds. | the factory (static) and the engine (computed) |
|
|
29
|
+
| 4 | When both seeds have the same scope kind, leave the scope key out of the reference. The engine fills in the scope being seeded (`organizationId` on an organization `afterCreate`), and only when the target resource's business key contains that field. | the engine |
|
|
30
|
+
| 5 | A reference that names ANOTHER scope's id (`organizationId: 'org-2'` while seeding `org-1`) is refused, and so is a found row that belongs to another scope — which a target keyed without its scope field can return. Either would link one tenant's row to another's. | the engine, as an unresolved reference |
|
|
31
|
+
| 6 | The referenced row must exist. A reference in `data` that resolves to nothing fails THAT entry: it is reported on the run (`DataSeedRun.failureReport`, status PARTIAL) and not written, and the other entries are. A reference in `businessKey` that resolves to nothing fails the WHOLE run before anything is written, because the row's identity is unknown. | the engine |
|
|
32
|
+
|
|
33
|
+
Nothing is ever written with a `null` or a placeholder foreign key.
|
|
34
|
+
|
|
35
|
+
## Where a reference may sit
|
|
36
|
+
|
|
37
|
+
- In static `entries` and in a computed `entry()`.
|
|
38
|
+
- In `data` and in `businessKey` — a junction row keyed by the two ids it joins puts both
|
|
39
|
+
references in its business key.
|
|
40
|
+
- Directly as a field value, or inside nested objects and arrays (`tagIds: [ref, ref]`).
|
|
41
|
+
- In every mode (`ADDITIVE`, `UPGRADE`, `SYNC`, `LAZY`) and on every trigger level, including manual
|
|
42
|
+
reruns.
|
|
43
|
+
|
|
44
|
+
## Reading a failure
|
|
45
|
+
|
|
46
|
+
An unresolved reference names everything needed to fix it:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
seed 'crm:demo-contacts' did not write this entry: a reference in its data resolves to no row.
|
|
50
|
+
data.customerId → seed 'crm:demo-customers' row {"email":"ana@example.com"}:
|
|
51
|
+
no 'customers' row has the business key {"email":"ana@example.com","organizationId":"…"}.
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Check, in order: that the referenced seed ran for this scope (it is in `dependsOn`, so it ran first
|
|
55
|
+
in the same pass unless it failed — its own run says so), and that one of its entries has exactly
|
|
56
|
+
this business key.
|
|
57
|
+
|
|
58
|
+
## Not supported
|
|
59
|
+
|
|
60
|
+
- **A seed referencing its own rows** (a category tree in one seed). Split the levels into two seeds.
|
|
61
|
+
- **A reference across scope kinds whose target key holds the target's scope id** — an `ORGANIZATION`
|
|
62
|
+
seed naming an `APPLICATION`-scoped catalog row keyed `(applicationId, code)`. The scope id is filled
|
|
63
|
+
in only when both seeds have the same scope kind, and a static entry cannot write the application's
|
|
64
|
+
id, so such a reference never resolves. Seed the linking rows at the target's scope kind, or key the
|
|
65
|
+
target by fields that do not include its scope.
|
|
66
|
+
- **A reference resolved later**, once the target appears. A reference resolves when the referring
|
|
67
|
+
seed runs, and fails if the row is not there then. Order the seeds with `dependsOn`.
|