@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
|
@@ -32,8 +32,9 @@ A custom operation file is the spot where:
|
|
|
32
32
|
|
|
33
33
|
1. **Custom validation** beyond Zod runs (cross-field constraints,
|
|
34
34
|
tenant-aware rules, async validation against external systems)
|
|
35
|
-
2. **Side effects** are coordinated with the operation;
|
|
36
|
-
|
|
35
|
+
2. **Side effects** are coordinated with the operation; which mechanism fits
|
|
36
|
+
depends on whether the work may be lost after commit — see
|
|
37
|
+
`references/after-the-operation.md`
|
|
37
38
|
3. **Pipeline composition** layers custom logic on top of the
|
|
38
39
|
framework's generic CRUD path through lifecycle hooks
|
|
39
40
|
4. **Cross-resource orchestration** can opt into an explicit transactional
|
|
@@ -87,8 +88,10 @@ the resource configuration declares it:
|
|
|
87
88
|
|
|
88
89
|
- `resourceIdentifier: <ModuleResourceType>.<ENUM_MEMBER>` (typed
|
|
89
90
|
enum reference)
|
|
90
|
-
- `operationIdentifier: CoreResourceOperation.*` (
|
|
91
|
-
|
|
91
|
+
- `operationIdentifier: CoreResourceOperation.*` for a core verb (`CREATE`, `UPDATE`, `DELETE`,
|
|
92
|
+
etc.), or the resource's OWN custom-operation enum member for a business verb the configuration
|
|
93
|
+
declares (`Quote_Operations.ACCEPT`, `Invoice_Operations.ISSUE`). A custom operation is wired
|
|
94
|
+
exactly like a core one.
|
|
92
95
|
- `variantType: ResourceOperationVariantType.*` (typed enum:
|
|
93
96
|
`API_CALL`, etc.)
|
|
94
97
|
- **the variant's identity**: `isOperationDefault: true` for the variant configured `isDefault: true`,
|
|
@@ -214,8 +217,10 @@ Each handler is optional. Common patterns:
|
|
|
214
217
|
transaction in `utils.serviceOptions`. They cannot run when the operation
|
|
215
218
|
reuses a caller-owned transaction, because the nested result must return
|
|
216
219
|
before that caller can commit. A terminal-hook failure after a framework
|
|
217
|
-
commit rejects the response but cannot roll the mutation back
|
|
218
|
-
|
|
220
|
+
commit rejects the response but cannot roll the mutation back. External work
|
|
221
|
+
that must not be lost is recorded on the row and finished by a minion — see
|
|
222
|
+
`references/after-the-operation.md`, which also says why an application has
|
|
223
|
+
no durable post-commit hook.
|
|
219
224
|
|
|
220
225
|
Use `utils.logger` for logs; never `console.log`. Throw typed
|
|
221
226
|
backend errors and catch them with `isWildoBackendError(error)`.
|
|
@@ -336,6 +341,230 @@ rollback; nested resource calls must preserve `utils.serviceOptions`. Neither
|
|
|
336
341
|
case is established merely by declaring a postfix, and this example declares
|
|
337
342
|
neither transaction ownership nor a caller transaction.
|
|
338
343
|
|
|
344
|
+
### Worked Example 2: an operation that creates another resource
|
|
345
|
+
|
|
346
|
+
The shape of a conversion — "an accepted quote creates a job", "invoice this job" — is an
|
|
347
|
+
operation that writes a record of ANOTHER resource inside its own transaction. This custom
|
|
348
|
+
operation finds (or first creates) the organization's inbox list and files the new todo there:
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
## Usage Example
|
|
352
|
+
|
|
353
|
+
```typescript
|
|
354
|
+
/**
|
|
355
|
+
* `quick-add` — capture a todo from anywhere, into the organization's inbox unless a list is named.
|
|
356
|
+
*
|
|
357
|
+
* ## What PREFIX decides
|
|
358
|
+
*
|
|
359
|
+
* The one thing the caller did not: which list the todo belongs to. A request that names a list keeps
|
|
360
|
+
* it, and the core CREATE's own write-integrity guard checks that list exists in this organization,
|
|
361
|
+
* exactly as it does for the ordinary CREATE. A request that names none is given the inbox — the list
|
|
362
|
+
* whose `slug` is {@link TODOS_QUICK_ADD_INBOX_LIST_SLUG} — which is created the first time an
|
|
363
|
+
* organization captures into it.
|
|
364
|
+
*
|
|
365
|
+
* ## The inbox is found by slug whatever its status
|
|
366
|
+
*
|
|
367
|
+
* An ARCHIVED inbox is still the inbox: `slug` is unique per organization regardless of status, so
|
|
368
|
+
* creating a second one beside it would be refused by the same unique index that guarantees there is
|
|
369
|
+
* only one. The capture therefore lands there and the organization, which archived it, restores it
|
|
370
|
+
* when it wants its backlog back. The todo itself is created, reachable and counted either way.
|
|
371
|
+
*
|
|
372
|
+
* ## Atomicity and the first-capture race
|
|
373
|
+
*
|
|
374
|
+
* `transactionalCore` makes the inbox creation and the todo one boundary: a capture that fails leaves
|
|
375
|
+
* no empty inbox behind. Two first captures in the same organization at the same instant both see no
|
|
376
|
+
* inbox and both create one; the unique `slug` index refuses the loser, and the conflict resolver
|
|
377
|
+
* spends the framework's single bounded retry — on which the loser finds the winner's inbox and
|
|
378
|
+
* files its todo there. A second conflict is not retried again: the resolver is only asked once.
|
|
379
|
+
*/
|
|
380
|
+
const todosQuickAddCustomImpl: ResourceCustomServiceImplementationFactory = (
|
|
381
|
+
resourcesRegistryService: ResourcesRegistryBackendService,
|
|
382
|
+
) => {
|
|
383
|
+
const operationPath = {
|
|
384
|
+
resourceIdentifier: TasksManager_ResourceType.TODOS,
|
|
385
|
+
operationIdentifier: Todos_Operations.QUICK_ADD,
|
|
386
|
+
variantType: ResourceOperationVariantType.API_CALL,
|
|
387
|
+
isOperationDefault: true,
|
|
388
|
+
};
|
|
389
|
+
const requestDtoSchema = resourcesRegistryService.getRequestDtoFromPath(operationPath);
|
|
390
|
+
const responseDtoSchema = resourcesRegistryService.getResponseDtoFromPath(operationPath);
|
|
391
|
+
|
|
392
|
+
return createResourceCustomServiceImplementation<typeof requestDtoSchema, typeof responseDtoSchema>({
|
|
393
|
+
operationPath,
|
|
394
|
+
requestDtoSchema,
|
|
395
|
+
responseDtoSchema,
|
|
396
|
+
transactionalCore: true,
|
|
397
|
+
// `todos` is included automatically as the operation's own resource; the inbox lookup and its
|
|
398
|
+
// first-use creation are the one additional resource these phases touch.
|
|
399
|
+
transactionParticipants: {
|
|
400
|
+
inboxList: TasksManager_ResourceType.TODO_LISTS,
|
|
401
|
+
},
|
|
402
|
+
// The only unique constraint this boundary can trip is the inbox's per-organization `slug`, and
|
|
403
|
+
// the retry is what resolves it (see the class comment). A todo has no unique field of its own.
|
|
404
|
+
transactionalCoreConflictResolver: async () => ({
|
|
405
|
+
action: ResourceCustomServiceImplementationTransactionalCoreConflictAction.RETRY_TRANSACTION,
|
|
406
|
+
}),
|
|
407
|
+
handlers: {
|
|
408
|
+
prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
|
|
409
|
+
const capture = input as Todos_QuickAddRequest;
|
|
410
|
+
if (capture.todoListId) {
|
|
411
|
+
return input;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
// Scoped to the caller's organization by the sub-call context, so this can only ever find
|
|
415
|
+
// THIS organization's inbox. Every nested call forwards the operation's options, or it would
|
|
416
|
+
// read and write outside the transaction it belongs to.
|
|
417
|
+
const listed = await utils.servicesRegistry.list<TodoLists>(
|
|
418
|
+
TasksManager_ResourceType.TODO_LISTS,
|
|
419
|
+
await utils.executionContextCreator.createForSubCall(
|
|
420
|
+
executionContext,
|
|
421
|
+
TasksManager_ResourceType.TODO_LISTS,
|
|
422
|
+
CoreResourceOperation.LIST,
|
|
423
|
+
utils.serviceOptions,
|
|
424
|
+
),
|
|
425
|
+
{ slug: TODOS_QUICK_ADD_INBOX_LIST_SLUG },
|
|
426
|
+
undefined,
|
|
427
|
+
utils.serviceOptions,
|
|
428
|
+
);
|
|
429
|
+
const existingInbox = (Array.isArray(listed) ? listed : (listed?.data ?? []))[0];
|
|
430
|
+
|
|
431
|
+
const inbox = existingInbox ?? await utils.servicesRegistry.create<TodoLists>(
|
|
432
|
+
TasksManager_ResourceType.TODO_LISTS,
|
|
433
|
+
await utils.executionContextCreator.createForSubCall(
|
|
434
|
+
executionContext,
|
|
435
|
+
TasksManager_ResourceType.TODO_LISTS,
|
|
436
|
+
CoreResourceOperation.CREATE,
|
|
437
|
+
utils.serviceOptions,
|
|
438
|
+
),
|
|
439
|
+
{ name: TODOS_QUICK_ADD_INBOX_LIST_NAME, slug: TODOS_QUICK_ADD_INBOX_LIST_SLUG },
|
|
440
|
+
utils.serviceOptions,
|
|
441
|
+
);
|
|
442
|
+
|
|
443
|
+
if (!existingInbox) {
|
|
444
|
+
utils.logger.info('Created the organization inbox list for a quick-add capture', { todoListId: inbox._id });
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
return { ...capture, todoListId: inbox._id };
|
|
448
|
+
},
|
|
449
|
+
},
|
|
450
|
+
});
|
|
451
|
+
};
|
|
452
|
+
|
|
453
|
+
export default todosQuickAddCustomImpl;
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
What earns its place, and what to copy for a conversion:
|
|
457
|
+
|
|
458
|
+
- `transactionalCore: true` plus `transactionParticipants: { inboxList: … }` — the source write and
|
|
459
|
+
the related write are one boundary, so a failure leaves no half-converted pair. Name every
|
|
460
|
+
resource the hooks touch besides the operation's own.
|
|
461
|
+
- `utils.servicesRegistry.create<T>(resourceType, subContext, payload, utils.serviceOptions)` — the
|
|
462
|
+
related record goes through that resource's own CREATE, so its validation, scope and audit apply.
|
|
463
|
+
Never write to its repository directly.
|
|
464
|
+
- `utils.executionContextCreator.createForSubCall(executionContext, resourceType, operation,
|
|
465
|
+
utils.serviceOptions)` — the nested call runs as the same caller, scoped to the same organization.
|
|
466
|
+
- `utils.serviceOptions` on EVERY nested call — without it the nested read and write run outside the
|
|
467
|
+
transaction they belong to.
|
|
468
|
+
- A conflict resolver when a unique constraint can race (here the inbox's slug), returning
|
|
469
|
+
`RETRY_TRANSACTION` once.
|
|
470
|
+
|
|
471
|
+
For a conversion, put the create in `postfixCoreOperations` of the source's transition (the quote's
|
|
472
|
+
ACCEPT), reading the source from the hook's result, and declare the target resource as a
|
|
473
|
+
participant. The transition itself is configured as in the `resource-status-lifecycle` skill.
|
|
474
|
+
|
|
475
|
+
### Worked Example 3: recording an audit event of your own
|
|
476
|
+
|
|
477
|
+
When an operation's FACT is what a reviewer looks for ("the quote was issued"), record it from the operation.
|
|
478
|
+
The factory's second parameter is the container; resolve the audit service from it on first use:
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
## Usage Example
|
|
482
|
+
|
|
483
|
+
```typescript
|
|
484
|
+
import { AuditEventCategory, AuditEventSeverity, ResourceOperationRiskLevel, ResourceOperationVariantType } from '@wildo-ai/saas-models';
|
|
485
|
+
import {
|
|
486
|
+
createResourceCustomServiceImplementation,
|
|
487
|
+
SAAS_SERVICE_TYPES,
|
|
488
|
+
type AuditLogsBackendService,
|
|
489
|
+
type InversifyContainer,
|
|
490
|
+
type ResourceCustomServiceImplementationFactory,
|
|
491
|
+
type ResourcesRegistryBackendService,
|
|
492
|
+
} from '@wildo-ai/saas-backend-lib';
|
|
493
|
+
|
|
494
|
+
/** In an application these come from its shared-lib (`Sales_ResourceType`, `Quotes_Operations`). */
|
|
495
|
+
enum Sales_ResourceType {
|
|
496
|
+
QUOTES = 'quotes',
|
|
497
|
+
}
|
|
498
|
+
enum Quotes_Operations {
|
|
499
|
+
ISSUE = 'issue',
|
|
500
|
+
}
|
|
501
|
+
/** The application's OWN event types, named once so the trail and every reader agree on the words. */
|
|
502
|
+
enum Sales_AuditEventType {
|
|
503
|
+
QUOTE_ISSUED = 'SALES_QUOTE_ISSUED',
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
/**
|
|
507
|
+
* How each of those event types is classified, declared ONCE as `auditTrail.applicationEventTypes` in the backend
|
|
508
|
+
* configuration (`backend-api/src/saas-config.backend.ts`). Rows of a declared type are recorded and routed to the
|
|
509
|
+
* SIEM with its category and severity, and the labelling pipeline plans its word; an undeclared type is recorded as
|
|
510
|
+
* `data_access` / `info`. Total over the enum by its type, so a new event type without a classification fails to compile.
|
|
511
|
+
*/
|
|
512
|
+
export const salesAuditEventTypes = {
|
|
513
|
+
[Sales_AuditEventType.QUOTE_ISSUED]: { category: AuditEventCategory.DATA_ACCESS, severity: AuditEventSeverity.WARNING },
|
|
514
|
+
} satisfies Record<Sales_AuditEventType, { category: AuditEventCategory; severity: AuditEventSeverity }>;
|
|
515
|
+
|
|
516
|
+
const quotesIssueCustomImpl: ResourceCustomServiceImplementationFactory = (
|
|
517
|
+
resourcesRegistryService: ResourcesRegistryBackendService,
|
|
518
|
+
container: InversifyContainer,
|
|
519
|
+
) => {
|
|
520
|
+
const operationPath = {
|
|
521
|
+
resourceIdentifier: Sales_ResourceType.QUOTES,
|
|
522
|
+
operationIdentifier: Quotes_Operations.ISSUE,
|
|
523
|
+
variantType: ResourceOperationVariantType.API_CALL,
|
|
524
|
+
isOperationDefault: true,
|
|
525
|
+
};
|
|
526
|
+
const requestDtoSchema = resourcesRegistryService.getRequestDtoFromPath(operationPath);
|
|
527
|
+
const responseDtoSchema = resourcesRegistryService.getResponseDtoFromPath(operationPath);
|
|
528
|
+
|
|
529
|
+
// Resolved on first use, never in the factory body: factories run while the container is still being populated.
|
|
530
|
+
let auditLogs: AuditLogsBackendService | undefined;
|
|
531
|
+
|
|
532
|
+
return createResourceCustomServiceImplementation<typeof requestDtoSchema, typeof responseDtoSchema>({
|
|
533
|
+
operationPath,
|
|
534
|
+
requestDtoSchema,
|
|
535
|
+
responseDtoSchema,
|
|
536
|
+
handlers: {
|
|
537
|
+
// The quote's ISSUE transition: the event is recorded once the issued state is the result.
|
|
538
|
+
postfixCoreOperations: async (id, result, executionContext, _operationPath, utils) => {
|
|
539
|
+
auditLogs ??= container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService);
|
|
540
|
+
// The event names WHO acted and WHICH organization it is about: the row is assembled from what you pass, and an
|
|
541
|
+
// organization's audit view lists only rows carrying its id. The context (second argument) adds what kind of
|
|
542
|
+
// principal acted (person, agent, machine), the correlation id and the organization's SIEM routing.
|
|
543
|
+
await auditLogs.logEvent({
|
|
544
|
+
eventType: Sales_AuditEventType.QUOTE_ISSUED,
|
|
545
|
+
riskLevel: ResourceOperationRiskLevel.MEDIUM,
|
|
546
|
+
userId: executionContext.initiatorIds?.userId,
|
|
547
|
+
organizationId: executionContext.initiatorIds?.organizationId,
|
|
548
|
+
eventData: { quoteId: id, quoteNumber: (result as { number?: string } | undefined)?.number },
|
|
549
|
+
}, executionContext);
|
|
550
|
+
utils.logger.debug('Recorded the quote issue in the audit trail');
|
|
551
|
+
return result;
|
|
552
|
+
},
|
|
553
|
+
},
|
|
554
|
+
});
|
|
555
|
+
};
|
|
556
|
+
|
|
557
|
+
export default quotesIssueCustomImpl;
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
- `logEvent(event, executionContext)` — the event names `userId` and `organizationId` from
|
|
561
|
+
`executionContext.initiatorIds` (the row is built from them, and the organization's audit view lists only rows
|
|
562
|
+
carrying its id), your `eventType` (a named enum), `riskLevel` and flat `eventData`. The context adds the
|
|
563
|
+
principal's kind, the correlation id and SIEM delivery.
|
|
564
|
+
- In a postfix without `transactionalCore`, the write has persisted, unless the operation was called inside another
|
|
565
|
+
operation's transaction. With `transactionalCore: true`, record from `atTheEnd` instead, which runs after commit.
|
|
566
|
+
Read `references/framework-audit-log-event-api.md` first.
|
|
567
|
+
|
|
339
568
|
## Rejecting from a hook: throw a WildoError, never `new Error`
|
|
340
569
|
|
|
341
570
|
When a hook must reject (custom validation fails, a business rule is violated,
|
|
@@ -369,6 +598,8 @@ map and the message/context rules.
|
|
|
369
598
|
- `references/operation-file-conventions.md` — operation file conventions
|
|
370
599
|
- `references/framework-operation-base-and-path-api.md` — source-backed operation identity / path types from `saas-models`
|
|
371
600
|
- `references/framework-transactional-core-api.md` — source-backed atomic core and named participant contract
|
|
601
|
+
- `references/after-the-operation.md` — which mechanism for work that follows an operation (another record, a notification, an audit event, an external call), and whether it can be lost
|
|
602
|
+
- `references/framework-audit-log-event-api.md` — source-backed `logEvent`: recording an application's own audit event, where to call it, and what such an event does not get
|
|
372
603
|
- `references/framework-error-handling-api.md` — source-backed `ErrorType` enum + the rules for throwing a WildoError (customMessageReference vs context, no plain `Error`)
|
|
373
604
|
- `backend-addon-wiring/SKILL.md` — module wiring (the consumer of the auto-scanned operations slot)
|
|
374
605
|
- `resource-config-wiring/SKILL.md` — resource configuration (the truth contract for DTO schemas)
|
|
@@ -386,6 +617,7 @@ map and the message/context rules.
|
|
|
386
617
|
- [ ] Handlers (when present) return the input or run side effects through `utils.<service>`
|
|
387
618
|
- [ ] Errors caught with `isWildoBackendError(error)`
|
|
388
619
|
- [ ] Logs use `utils.logger`, not `console.log`
|
|
620
|
+
- [ ] Every `logEvent(...)` call sets `userId` and `organizationId` from `executionContext.initiatorIds` and passes the request's `executionContext`; an application never calls `registerPostOperationHook`
|
|
389
621
|
- [ ] Operation invoked from API for the intended resource operation id
|
|
390
622
|
|
|
391
623
|
### Grep invariants
|
|
@@ -394,17 +626,30 @@ Run from the app root, substituting `<slug>` and `<resource>`:
|
|
|
394
626
|
|
|
395
627
|
| Invariant | Command |
|
|
396
628
|
|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
397
|
-
| File suffix is `*.operation.ts` |
|
|
629
|
+
| File suffix is `*.operation.ts` | see the commands below the table |
|
|
398
630
|
| Default export is the typed factory | `rg -n "export default" backend-api/src/modules/<slug>/resources/<resource>/<resource>.*.operation.ts` |
|
|
399
631
|
| `operationIdentifier` uses typed enum | `rg -n "operationIdentifier:\s+CoreResourceOperation\." backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
400
632
|
| `variantType` uses typed enum | `rg -n "variantType:\s+ResourceOperationVariantType\." backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
401
633
|
| **No string-literal `operationIdentifier`** (must be empty) | `rg -n "operationIdentifier:\s+'" backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
402
|
-
| DTO schemas resolved through the registry |
|
|
634
|
+
| DTO schemas resolved through the registry | see the commands below the table |
|
|
403
635
|
| Custom impl uses the typed factory | `rg -n "createResourceCustomServiceImplementation<" backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
404
636
|
| Transactional core declares its participant map | `rg -n -U "transactionalCore:\\s*true[\\s\\S]{0,240}transactionParticipants:" backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
405
|
-
| **No `console.log`** (must be empty; use `utils.logger`) |
|
|
637
|
+
| **No `console.log`** (must be empty; use `utils.logger`) | see the commands below the table |
|
|
406
638
|
| **No plain `throw new Error`** (use `utils.errorBuilder.buildError`) | `rg -n "throw new Error" backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
407
639
|
| **No prose in error context** (use `customMessageReference`) | `rg -n "context:\s*\{[^}]*message:\s*['\"\`]" backend-api/src/modules/<slug>/resources/<resource>/` |
|
|
640
|
+
| **Every `logEvent` names its actor, tenant and context** (each hit shows `userId:`, `organizationId:` and a second argument) | `rg -n -A10 "logEvent\(" backend-api/src/modules/<slug>/` |
|
|
641
|
+
| **No engine post-operation hook from application code** (must be empty) | `rg -n "registerPostOperationHook" backend-api/src` |
|
|
642
|
+
|
|
643
|
+
```bash
|
|
644
|
+
# File suffix is `*.operation.ts`
|
|
645
|
+
rg --files backend-api/src/modules/<slug>/resources/ | rg "\.operation\.ts$"
|
|
646
|
+
|
|
647
|
+
# DTO schemas resolved through the registry
|
|
648
|
+
rg -n "getRequestDtoFromPath\(operationPath\)|getResponseDtoFromPath\(operationPath\)" backend-api/src/modules/<slug>/resources/<resource>/
|
|
649
|
+
|
|
650
|
+
# No `console.log` (must be empty; use `utils.logger`)
|
|
651
|
+
rg -n "console\.(log|error|warn)" backend-api/src/modules/<slug>/resources/<resource>/
|
|
652
|
+
```
|
|
408
653
|
|
|
409
654
|
The high-signal invariant is **"`operationIdentifier` and
|
|
410
655
|
`variantType` use typed enums"** combined with **"DTO schemas
|
|
@@ -440,6 +685,8 @@ keep the operation aligned with the resource config as it evolves.
|
|
|
440
685
|
- `console.log` in handler body (catch with the **No `console.log`** grep — must be empty)
|
|
441
686
|
- `throw new Error(...)` inside a hook instead of `utils.errorBuilder.buildError(...)` (catch with the **No plain `throw new Error`** grep below)
|
|
442
687
|
- A hardcoded English sentence in `context.message` (or `context.errorMessage`) instead of a `customMessageReference` (catch with the **No prose in error context** grep below)
|
|
688
|
+
- A `logEvent` call without `userId` / `organizationId`, or without the request's `executionContext` — the row names no actor, the organization's audit view never lists it, and the organization's own SIEM never receives it (catch with the **Every `logEvent` names its actor, tenant and context** grep above)
|
|
689
|
+
- Application code calling `registerPostOperationHook` through the engine's services registry — it has no application door and loses work silently (catch with the **No engine post-operation hook** grep above; see `references/after-the-operation.md`)
|
|
443
690
|
- Operation file not bound in DI — handler never runs (catch by hitting the API path and observing the framework's "no custom impl" log)
|
|
444
691
|
|
|
445
692
|
## Related Skills
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Work that follows an operation
|
|
2
|
+
|
|
3
|
+
Read this when an operation has to cause something beyond its own write: another record, an email, an audit
|
|
4
|
+
event, a call to another system. Each need has one mechanism, and they differ in the one property that
|
|
5
|
+
matters: whether the work can be LOST after the operation committed.
|
|
6
|
+
|
|
7
|
+
| need | use | guarantee |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| change other data together with this write (a conversion: quote → job) | `postfixCoreOperations` with `transactionalCore: true` and the target declared in `transactionParticipants` (Worked Example 2) | atomic: both commit or neither |
|
|
10
|
+
| tell a person (email, in-app notification) | `userNotifications` on the operation — `resource-config-wiring`, `references/framework-user-notifications-api.md` | dispatched by the framework after commit, in the process: best effort, lost if it stops first |
|
|
11
|
+
| record a business event for a reviewer | `logEvent` — `references/framework-audit-log-event-api.md` | written at once; call it where the change is already durable |
|
|
12
|
+
| call another system, and the call must not be lost | record the intent on the row inside the transaction (a `pendingSyncAt`, a state), and let a minion find and perform it, idempotently — `minion-authoring` | survives a crash: the row says the work is owed until it is done |
|
|
13
|
+
| call another system, best effort | a declared worker, through `utils.workerClientFactory`, from a terminal hook — `worker-authoring` | lost if the process stops before or during the call |
|
|
14
|
+
| react to every write of a resource you do not own | not available to an application (see below) | — |
|
|
15
|
+
|
|
16
|
+
## Why there is no "durable post-commit hook" for application code
|
|
17
|
+
|
|
18
|
+
By default the framework runs an operation's post-commit effects (its audit row, its notifications) in the
|
|
19
|
+
process, right after commit. A process that stops in between loses them. A terminal hook (`atTheEnd`,
|
|
20
|
+
`afterUserNotifications`) is the same: after commit, in the request. The one durable relay the engine has
|
|
21
|
+
serves its own billing effects, and `postCommitEffectOwnership: IMPLEMENTATION_OUTBOX` is not a way into it:
|
|
22
|
+
no application-facing relay delivers what that mode captures (see `framework-transactional-core-api.md`).
|
|
23
|
+
|
|
24
|
+
So when work must survive, the durable record is the ROW: write the intent in the same transaction as the
|
|
25
|
+
change, and let something that runs on its own schedule finish it. That is the transactional-outbox pattern
|
|
26
|
+
with your own resource as the outbox. A framework notification has no durable variant: if losing one is
|
|
27
|
+
unacceptable, record on the row that it is owed, so its absence can be detected and acted on.
|
|
28
|
+
|
|
29
|
+
## Post-operation hooks are engine-internal
|
|
30
|
+
|
|
31
|
+
The engine registers observers on resource writes through `registerPostOperationHook` (the data-seeding
|
|
32
|
+
bootstrap and billing use it, once, at startup). The method is reachable — `utils.servicesRegistry` exposes it —
|
|
33
|
+
but an application owns no place to call it: there is no module slot for it, and a handler runs on every
|
|
34
|
+
request, so calling it there registers one more copy of the hook each time the operation runs. It is also best
|
|
35
|
+
effort: a hook's failure is logged, the write stands, and nothing retries it.
|
|
36
|
+
|
|
37
|
+
So for "when X changes, do Y":
|
|
38
|
+
|
|
39
|
+
- X is your own resource → a custom operation on X (a postfix, or a transition operation) does Y.
|
|
40
|
+
- Y must happen even if the process stops → the row-as-outbox pattern above.
|
|
41
|
+
- X is an engine resource you do not own → there is no application mechanism today. Do not reach into the
|
|
42
|
+
engine's services registry to register one.
|
package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md
ADDED
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
# Recording an audit event of your own
|
|
2
|
+
|
|
3
|
+
Read this when an operation must leave evidence the framework does not write for you: a business event a
|
|
4
|
+
reviewer will look for ("the quote was issued", "the client was notified"), or the committed event an
|
|
5
|
+
`overrideAll` implementation owes because it bypasses the framework's own post-commit lane.
|
|
6
|
+
|
|
7
|
+
Check first whether you need it at all. Every write-shaped `HIGH` / `CRITICAL` operation already emits an
|
|
8
|
+
operation-performed row, and `auditableEvent.auditBelowRiskFloor` extends that to a lower-risk verb (see
|
|
9
|
+
`resource-config-wiring/references/framework-operation-audit-api.md`). Your own event is for a FACT the
|
|
10
|
+
operation row does not name.
|
|
11
|
+
|
|
12
|
+
## How to reach it
|
|
13
|
+
|
|
14
|
+
A custom operation factory receives the dependency container as its second parameter. Resolve
|
|
15
|
+
`SAAS_SERVICE_TYPES.AuditLogsService` from it on first use, inside a handler, never in the factory body:
|
|
16
|
+
factories run while the container is still being populated. Both come from `@wildo-ai/saas-backend-lib`.
|
|
17
|
+
|
|
18
|
+
## What to pass
|
|
19
|
+
|
|
20
|
+
- `eventType` — from your own named enum (`Sales_AuditEventType.QUOTE_ISSUED`), never an inline string. Prefix
|
|
21
|
+
it with your domain so it cannot collide with a framework event type.
|
|
22
|
+
- `riskLevel` — how much a reviewer should care, on the same scale as operations.
|
|
23
|
+
- `eventData` — a flat object of ids and states. Never a secret, never free personal text: the trail is
|
|
24
|
+
retained for years and exported to the operator's SIEM.
|
|
25
|
+
- `userId` and `organizationId` — WHO acted and WHICH tenant the event is about, from
|
|
26
|
+
`executionContext.initiatorIds`. The row is built from what you pass: leave them out and the row names no
|
|
27
|
+
actor, and the organization's own audit view never lists it, because that view shows only rows carrying its id.
|
|
28
|
+
- the REQUEST's `executionContext` as the second argument. It adds what you cannot set: the kind of principal
|
|
29
|
+
that acted (a person, an agent, a machine, through which client), the correlation id, and delivery to the
|
|
30
|
+
organization's SIEM.
|
|
31
|
+
|
|
32
|
+
Leave the third argument (`principal`) alone unless the code runs with no request at all (an automation). It
|
|
33
|
+
REPLACES the context's principal, so passing a user id while holding a delegated or machine context records
|
|
34
|
+
that client's action as the person's own.
|
|
35
|
+
|
|
36
|
+
## Where to call it
|
|
37
|
+
|
|
38
|
+
`logEvent` writes at once. Call it where the effect it records is already durable:
|
|
39
|
+
|
|
40
|
+
- without `transactionalCore`, in `postfixCoreOperations`: the core write has persisted by then — unless the
|
|
41
|
+
operation was itself called inside another operation's transaction (a nested call forwarding
|
|
42
|
+
`utils.serviceOptions`). Then nothing has committed yet, and the event would survive a rollback of the change
|
|
43
|
+
it records; record it in the outer operation instead;
|
|
44
|
+
- with `transactionalCore: true`, in `atTheEnd`: it runs after the root commit. A postfix there is still
|
|
45
|
+
inside the transaction, and an event recorded from it would claim a change that a later rollback undoes.
|
|
46
|
+
|
|
47
|
+
Emission is fire-and-forget: a failure to record is logged and never fails the operation.
|
|
48
|
+
|
|
49
|
+
## Classify and word your event type
|
|
50
|
+
|
|
51
|
+
Declare each of your event types once, in the backend configuration's `auditTrail` block
|
|
52
|
+
(`backend-api/src/saas-config.backend.ts`), keyed by the exact `eventType` string:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
auditTrail: {
|
|
56
|
+
applicationEventTypes: {
|
|
57
|
+
[Sales_AuditEventType.QUOTE_ISSUED]: { category: AuditEventCategory.DATA_ACCESS, severity: AuditEventSeverity.WARNING },
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- **Classification.** Every row of that type is recorded with the declared `eventCategory` and `severity`, and the
|
|
63
|
+
organization's SIEM export routes and filters by them. An undeclared type is recorded as `data_access` / `info`
|
|
64
|
+
whatever its `riskLevel`, so a business-critical event looks like a routine read. `riskLevel` is a separate,
|
|
65
|
+
per-emission signal and does not change the severity.
|
|
66
|
+
- **Words.** The labelling pipeline plans `system_enums.CoreAuditableEventType.<eventType>` for each declared type,
|
|
67
|
+
so the audit views show "Quote issued" instead of `SALES_QUOTE_ISSUED`. Run label generation after adding one.
|
|
68
|
+
An undeclared type shows its raw value: a missing label that looks missing on purpose.
|
|
69
|
+
- **Limits.** You cannot reclassify a framework event type: startup refuses a declaration that names one. The key
|
|
70
|
+
must use only letters, digits, `_` and `-`.
|
|
71
|
+
|
|
72
|
+
The full contract of the `auditTrail` block is in `config-saas/references/framework-audit-trail-config-api.md`.
|
|
73
|
+
|
|
74
|
+
## Worked example
|
|
75
|
+
|
|
76
|
+
A quote's ISSUE transition records the application's own event, through the factory's container:
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
## Usage Example
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
import { AuditEventCategory, AuditEventSeverity, ResourceOperationRiskLevel, ResourceOperationVariantType } from '@wildo-ai/saas-models';
|
|
83
|
+
import {
|
|
84
|
+
createResourceCustomServiceImplementation,
|
|
85
|
+
SAAS_SERVICE_TYPES,
|
|
86
|
+
type AuditLogsBackendService,
|
|
87
|
+
type InversifyContainer,
|
|
88
|
+
type ResourceCustomServiceImplementationFactory,
|
|
89
|
+
type ResourcesRegistryBackendService,
|
|
90
|
+
} from '@wildo-ai/saas-backend-lib';
|
|
91
|
+
|
|
92
|
+
/** In an application these come from its shared-lib (`Sales_ResourceType`, `Quotes_Operations`). */
|
|
93
|
+
enum Sales_ResourceType {
|
|
94
|
+
QUOTES = 'quotes',
|
|
95
|
+
}
|
|
96
|
+
enum Quotes_Operations {
|
|
97
|
+
ISSUE = 'issue',
|
|
98
|
+
}
|
|
99
|
+
/** The application's OWN event types, named once so the trail and every reader agree on the words. */
|
|
100
|
+
enum Sales_AuditEventType {
|
|
101
|
+
QUOTE_ISSUED = 'SALES_QUOTE_ISSUED',
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* How each of those event types is classified, declared ONCE as `auditTrail.applicationEventTypes` in the backend
|
|
106
|
+
* configuration (`backend-api/src/saas-config.backend.ts`). Rows of a declared type are recorded and routed to the
|
|
107
|
+
* SIEM with its category and severity, and the labelling pipeline plans its word; an undeclared type is recorded as
|
|
108
|
+
* `data_access` / `info`. Total over the enum by its type, so a new event type without a classification fails to compile.
|
|
109
|
+
*/
|
|
110
|
+
export const salesAuditEventTypes = {
|
|
111
|
+
[Sales_AuditEventType.QUOTE_ISSUED]: { category: AuditEventCategory.DATA_ACCESS, severity: AuditEventSeverity.WARNING },
|
|
112
|
+
} satisfies Record<Sales_AuditEventType, { category: AuditEventCategory; severity: AuditEventSeverity }>;
|
|
113
|
+
|
|
114
|
+
const quotesIssueCustomImpl: ResourceCustomServiceImplementationFactory = (
|
|
115
|
+
resourcesRegistryService: ResourcesRegistryBackendService,
|
|
116
|
+
container: InversifyContainer,
|
|
117
|
+
) => {
|
|
118
|
+
const operationPath = {
|
|
119
|
+
resourceIdentifier: Sales_ResourceType.QUOTES,
|
|
120
|
+
operationIdentifier: Quotes_Operations.ISSUE,
|
|
121
|
+
variantType: ResourceOperationVariantType.API_CALL,
|
|
122
|
+
isOperationDefault: true,
|
|
123
|
+
};
|
|
124
|
+
const requestDtoSchema = resourcesRegistryService.getRequestDtoFromPath(operationPath);
|
|
125
|
+
const responseDtoSchema = resourcesRegistryService.getResponseDtoFromPath(operationPath);
|
|
126
|
+
|
|
127
|
+
// Resolved on first use, never in the factory body: factories run while the container is still being populated.
|
|
128
|
+
let auditLogs: AuditLogsBackendService | undefined;
|
|
129
|
+
|
|
130
|
+
return createResourceCustomServiceImplementation<typeof requestDtoSchema, typeof responseDtoSchema>({
|
|
131
|
+
operationPath,
|
|
132
|
+
requestDtoSchema,
|
|
133
|
+
responseDtoSchema,
|
|
134
|
+
handlers: {
|
|
135
|
+
// The quote's ISSUE transition: the event is recorded once the issued state is the result.
|
|
136
|
+
postfixCoreOperations: async (id, result, executionContext, _operationPath, utils) => {
|
|
137
|
+
auditLogs ??= container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService);
|
|
138
|
+
// The event names WHO acted and WHICH organization it is about: the row is assembled from what you pass, and an
|
|
139
|
+
// organization's audit view lists only rows carrying its id. The context (second argument) adds what kind of
|
|
140
|
+
// principal acted (person, agent, machine), the correlation id and the organization's SIEM routing.
|
|
141
|
+
await auditLogs.logEvent({
|
|
142
|
+
eventType: Sales_AuditEventType.QUOTE_ISSUED,
|
|
143
|
+
riskLevel: ResourceOperationRiskLevel.MEDIUM,
|
|
144
|
+
userId: executionContext.initiatorIds?.userId,
|
|
145
|
+
organizationId: executionContext.initiatorIds?.organizationId,
|
|
146
|
+
eventData: { quoteId: id, quoteNumber: (result as { number?: string } | undefined)?.number },
|
|
147
|
+
}, executionContext);
|
|
148
|
+
utils.logger.debug('Recorded the quote issue in the audit trail');
|
|
149
|
+
return result;
|
|
150
|
+
},
|
|
151
|
+
},
|
|
152
|
+
});
|
|
153
|
+
};
|
|
154
|
+
|
|
155
|
+
export default quotesIssueCustomImpl;
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## The contract
|
|
159
|
+
|
|
160
|
+
## Import Origins
|
|
161
|
+
|
|
162
|
+
- `@wildo-ai/saas-backend-lib`
|
|
163
|
+
|
|
164
|
+
## Source Excerpts
|
|
165
|
+
|
|
166
|
+
### Origin Package: `@wildo-ai/saas-backend-lib`
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
/**
|
|
170
|
+
* What an emitter hands to the audit pipeline: the event, minus everything the pipeline derives.
|
|
171
|
+
*
|
|
172
|
+
* You supply `eventType` (your own named vocabulary), `riskLevel`, `eventData` (a flat object of the facts a reviewer
|
|
173
|
+
* needs — ids and states, never secrets or free personal text), and the row's subjects: `userId` (the actor) and
|
|
174
|
+
* `organizationId` (the tenant the event is about). The row is built from what you pass, and an organization's audit
|
|
175
|
+
* view lists only rows carrying its id, so take both from the request: `executionContext.initiatorIds`.
|
|
176
|
+
*
|
|
177
|
+
* Derived, never supplied: `eventId`, `eventCategory`, `severity`, the timestamps, and the principal's kind and
|
|
178
|
+
* delegation (person, agent, machine, through which client) — read from the execution context you pass to `logEvent`.
|
|
179
|
+
* Those are omitted from this type and discarded at runtime.
|
|
180
|
+
*/
|
|
181
|
+
export type AuditEventEmission = Omit<AuditableEvent, '_id' | 'eventId' | 'createdAt' | 'updatedAt' | 'eventCategory' | 'severity' | AuditRowAttributionField>;
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Origin Package: `@wildo-ai/saas-backend-lib`
|
|
185
|
+
|
|
186
|
+
```typescript
|
|
187
|
+
/**
|
|
188
|
+
* Generic audit-event emitter: how application code records an event of its own.
|
|
189
|
+
*
|
|
190
|
+
* Reach it from a custom operation through the factory's container parameter, resolved on first use:
|
|
191
|
+
* `container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService)` (both from
|
|
192
|
+
* `@wildo-ai/saas-backend-lib`).
|
|
193
|
+
*
|
|
194
|
+
* Accepts any `eventType` string. The application classifies its OWN event types in its backend configuration,
|
|
195
|
+
* `auditTrail.applicationEventTypes: { [eventType]: { category, severity } }`; a declared type is recorded, and
|
|
196
|
+
* routed to the SIEM, with that classification, and the labelling pipeline plans a word for it. An undeclared one is
|
|
197
|
+
* recorded as `{ category: 'data_access', severity: 'info' }`. A framework event type keeps the engine's classification.
|
|
198
|
+
*
|
|
199
|
+
* Per-org SIEM dispatch fires ONLY when an authenticated request `ExecutionContext`
|
|
200
|
+
* (carrying an org) is passed as `requestExecutionContext` — never on the caller-supplied
|
|
201
|
+
* `organizationId` field, which says which tenant the row is ABOUT (tenant segregation).
|
|
202
|
+
*
|
|
203
|
+
* Errors are caught + logged but never thrown — audit emission is
|
|
204
|
+
* fire-and-forget; a logging failure must not affect the request
|
|
205
|
+
* that triggered it.
|
|
206
|
+
*/
|
|
207
|
+
public async logEvent(
|
|
208
|
+
auditEvent: AuditEventEmission,
|
|
209
|
+
requestExecutionContext?: ExecutionContext<any>,
|
|
210
|
+
/**
|
|
211
|
+
* The principal, when the caller knows it better than any context it holds (automation, a machine door).
|
|
212
|
+
* It REPLACES the context's principal wholesale: kind, delegating client and machine credential. So never
|
|
213
|
+
* pass `userAuditPrincipal(id)` while holding a delegated or machine context; pass the context instead, or
|
|
214
|
+
* the row will call a delegated client's action the person's own.
|
|
215
|
+
*/
|
|
216
|
+
principal?: AuditPrincipalFacts,
|
|
217
|
+
): Promise<void> {
|
|
218
|
+
return this._createAuditLog(auditEvent, requestExecutionContext, undefined, undefined, undefined, undefined, principal);
|
|
219
|
+
}
|
|
220
|
+
```
|
|
@@ -108,6 +108,11 @@ and populates the single source of truth. Consumers (app shell, website, docs,
|
|
|
108
108
|
email, PDF, schema.org) resolve their asset by `(composition, theme)` — no
|
|
109
109
|
per-consumer logo URLs.
|
|
110
110
|
|
|
111
|
+
To draw it outside the build, run `wildo creation brand logo` at the
|
|
112
|
+
application root: the same deliberation and accept the build step runs. It
|
|
113
|
+
refuses when a mark is already accepted; `wildo creation brand logo --redraw`
|
|
114
|
+
replaces it deliberately.
|
|
115
|
+
|
|
111
116
|
**Generating is not placing.** Accepting a mark writes the source of truth;
|
|
112
117
|
placing it in every surface is propagation. The companion propagates every time a
|
|
113
118
|
mark is accepted (from the workbench or by the logo step), and again whenever the
|