@wildo-ai/framework-knowledge 1.1.0
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/LICENSE +34 -0
- package/dist/esm/.builder.pid +9 -0
- package/dist/esm/framework-knowledge.definitions.d.ts +51 -0
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.definitions.js +1571 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -0
- package/dist/esm/framework-knowledge.loader.d.ts +72 -0
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.loader.js +258 -0
- package/dist/esm/framework-knowledge.loader.js.map +1 -0
- package/dist/esm/framework-knowledge.schemas.d.ts +236 -0
- package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.schemas.js +23 -0
- package/dist/esm/framework-knowledge.schemas.js.map +1 -0
- package/dist/esm/index.d.ts +4 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +4 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +53 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +56 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +200 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +228 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +39 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +39 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +261 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +412 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +61 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +65 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +53 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +54 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +43 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +73 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +53 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +114 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +95 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +102 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +258 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +241 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +241 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +202 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +82 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +89 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +56 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +76 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +30 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +27 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +31 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +26 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +254 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +219 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +180 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +302 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +249 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +286 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +248 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +227 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +45 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +48 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +250 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +218 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -0
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -0
- package/dist/knowledge/manifest.json +45 -0
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +407 -0
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +69 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +556 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +47 -0
- package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +344 -0
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +43 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +259 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +83 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +321 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +79 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +185 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +66 -0
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +737 -0
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +44 -0
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +261 -0
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +57 -0
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +151 -0
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +124 -0
- package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.business-model/method.md +128 -0
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +102 -0
- package/dist/knowledge/playbooks/top_down.business-model/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.capability-map/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.capability-map/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +239 -0
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +73 -0
- package/dist/knowledge/playbooks/top_down.capability-map/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +177 -0
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +95 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/method.md +64 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +49 -0
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +56 -0
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +40 -0
- package/dist/knowledge/playbooks/top_down.market-research/method.md +68 -0
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +42 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +239 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +69 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/method.md +96 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +77 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +53 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +61 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +280 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +87 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +204 -0
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +54 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +146 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +120 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/structured-artifact-action.json +1 -0
- package/dist/knowledge/references/application.database.migration-change-risk.md +28 -0
- package/dist/knowledge/references/assertions.authored-metadata.config.md +90 -0
- package/dist/knowledge/references/assertions.behaviors.wire-contracts.md +223 -0
- package/dist/knowledge/references/assertions.references.conventions.md +92 -0
- package/dist/knowledge/references/assertions.snapshot.validation.md +317 -0
- package/dist/knowledge/references/assertions.specification.config.md +287 -0
- package/dist/knowledge/references/brand.asset.config.md +167 -0
- package/dist/knowledge/references/brand.authored-metadata.config.md +51 -0
- package/dist/knowledge/references/brand.logo-direction.config.md +88 -0
- package/dist/knowledge/references/brand.name.config.md +46 -0
- package/dist/knowledge/references/brand.snapshot.config.md +76 -0
- package/dist/knowledge/references/brand.snapshot.validation.md +446 -0
- package/dist/knowledge/references/brand.visual-tone.config.md +56 -0
- package/dist/knowledge/references/build-plan.task-graph.config.md +198 -0
- package/dist/knowledge/references/business-model.authored-metadata.config.md +65 -0
- package/dist/knowledge/references/business-model.pricing-plan.config.md +122 -0
- package/dist/knowledge/references/business-model.references.conventions.md +99 -0
- package/dist/knowledge/references/business-model.snapshot.config.md +121 -0
- package/dist/knowledge/references/business-model.snapshot.validation.md +325 -0
- package/dist/knowledge/references/cli.market.generate-command.md +230 -0
- package/dist/knowledge/references/cli.market.utils.md +147 -0
- package/dist/knowledge/references/companion.introspection.behaviors.market.md +90 -0
- package/dist/knowledge/references/companion.introspection.handlers.market.md +42 -0
- package/dist/knowledge/references/companion.market.generation-service.md +270 -0
- package/dist/knowledge/references/companion.market.prompt-renderer.md +244 -0
- package/dist/knowledge/references/companion.technical-doc.service.md +809 -0
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +125 -0
- package/dist/knowledge/references/engine.client-bundle.discipline.md +130 -0
- package/dist/knowledge/references/engine.client-bundle.external-connectors-public.discipline.md +55 -0
- package/dist/knowledge/references/engine.saas-technical-doc.config.md +215 -0
- package/dist/knowledge/references/engine.saas-website.config.md +331 -0
- package/dist/knowledge/references/example.authorization.unit-narrowing.declaration.md +24 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +55 -0
- package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +35 -0
- package/dist/knowledge/references/example.backend.operation.error-throw.md +17 -0
- package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +63 -0
- package/dist/knowledge/references/example.config.app-shell.full.md +147 -0
- package/dist/knowledge/references/example.config.app-shell.hosted-components.md +45 -0
- package/dist/knowledge/references/example.config.app-shell.quick-switcher-fields.md +37 -0
- package/dist/knowledge/references/example.config.backend.billing-enable.md +20 -0
- package/dist/knowledge/references/example.config.backend.required-floors.md +46 -0
- package/dist/knowledge/references/example.config.design-system.full.md +162 -0
- package/dist/knowledge/references/example.config.navigation.full.md +71 -0
- package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +27 -0
- package/dist/knowledge/references/example.data-seeding.minimal.md +114 -0
- package/dist/knowledge/references/example.email.template.minimal.md +54 -0
- package/dist/knowledge/references/example.engine.component-registration.lazy-load.md +16 -0
- package/dist/knowledge/references/example.engine.product-definitions.feature-and-profiles.md +146 -0
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +196 -0
- package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +174 -0
- package/dist/knowledge/references/example.i18n.label-generation.engine-barrel.md +15 -0
- package/dist/knowledge/references/example.infra.cdn.cloudflare.md +23 -0
- package/dist/knowledge/references/example.infra.cdn.generic.md +17 -0
- package/dist/knowledge/references/example.infra.environment-config.local.md +250 -0
- package/dist/knowledge/references/example.market.alternative.in-house-build.md +49 -0
- package/dist/knowledge/references/example.market.authored-metadata.md +32 -0
- package/dist/knowledge/references/example.market.buying-journey.core-icp.md +140 -0
- package/dist/knowledge/references/example.market.category.config.md +71 -0
- package/dist/knowledge/references/example.market.channel.community.md +39 -0
- package/dist/knowledge/references/example.market.feature-benefit.kano-threshold.md +67 -0
- package/dist/knowledge/references/example.market.feature-benefit.pain-reliever.md +65 -0
- package/dist/knowledge/references/example.market.icp.anti-target.md +47 -0
- package/dist/knowledge/references/example.market.icp.individual.md +82 -0
- package/dist/knowledge/references/example.market.icp.legal-entity-with-geographies.md +95 -0
- package/dist/knowledge/references/example.market.is-benefit-available.composition.md +40 -0
- package/dist/knowledge/references/example.market.job.emotional.md +27 -0
- package/dist/knowledge/references/example.market.job.functional.md +28 -0
- package/dist/knowledge/references/example.market.message-template.seeds.md +106 -0
- package/dist/knowledge/references/example.market.objection.pricing.md +39 -0
- package/dist/knowledge/references/example.market.persona.dmu-with-inheritance.md +62 -0
- package/dist/knowledge/references/example.market.persona.individual-self.md +51 -0
- package/dist/knowledge/references/example.market.positioning.per-icp.md +103 -0
- package/dist/knowledge/references/example.market.proof.metric.md +39 -0
- package/dist/knowledge/references/example.market.scoring.golden-case.md +46 -0
- package/dist/knowledge/references/example.market.scoring.no-coverage-zero.md +40 -0
- package/dist/knowledge/references/example.market.snapshot-validation.duplicate-journey-stage.md +36 -0
- package/dist/knowledge/references/example.market.snapshot-validation.errors-by-kind.md +55 -0
- package/dist/knowledge/references/example.market.snapshot-validation.objection-proof-benefit-mismatch.md +74 -0
- package/dist/knowledge/references/example.market.snapshot-validation.proof-without-support.md +32 -0
- package/dist/knowledge/references/example.market.snapshot-validation.threshold-without-job.md +44 -0
- package/dist/knowledge/references/example.market.snapshot.assembled.md +49 -0
- package/dist/knowledge/references/example.market.tone-of-voice.config.md +41 -0
- package/dist/knowledge/references/example.market.trigger.growth-milestone.md +43 -0
- package/dist/knowledge/references/example.module.companion-exports.full.md +142 -0
- package/dist/knowledge/references/example.module.registration.shared.md +16 -0
- package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +47 -0
- package/dist/knowledge/references/example.module.relationships.discriminator.md +25 -0
- package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +25 -0
- package/dist/knowledge/references/example.provider.backend-module-shape.md +110 -0
- package/dist/knowledge/references/example.provider.contribution.backend-billing.md +12 -0
- package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +30 -0
- package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +21 -0
- package/dist/knowledge/references/example.rag.source-fields.declaration.md +83 -0
- package/dist/knowledge/references/example.rate-limit.custom-controller-surface.md +25 -0
- package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +24 -0
- package/dist/knowledge/references/example.resource.add-field.priority-enum.md +19 -0
- package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +21 -0
- package/dist/knowledge/references/example.resource.config-wiring.fk-relationship.md +33 -0
- package/dist/knowledge/references/example.resource.custom-view.read-host.md +28 -0
- package/dist/knowledge/references/example.resource.mcp-exposure.md +65 -0
- package/dist/knowledge/references/example.resource.reference-constraints.role-constrained.md +27 -0
- package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +22 -0
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +43 -0
- package/dist/knowledge/references/example.spec.composite-view.workspace.md +72 -0
- package/dist/knowledge/references/example.spec.feature.flag-with-codehandling.md +64 -0
- package/dist/knowledge/references/example.spec.frontend-component.prop-vocabulary.md +88 -0
- package/dist/knowledge/references/example.spec.resource.semantic-field.md +23 -0
- package/dist/knowledge/references/example.views.app-level.composite-views-config.md +19 -0
- package/dist/knowledge/references/example.views.chart-view.resource-owned.md +69 -0
- package/dist/knowledge/references/example.views.composite-view.host-embeds.md +31 -0
- package/dist/knowledge/references/example.views.composite-view.workspace.md +65 -0
- package/dist/knowledge/references/example.views.custom-view.execution-host.md +41 -0
- package/dist/knowledge/references/example.views.execution-view.resource-owned.md +25 -0
- package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +42 -0
- package/dist/knowledge/references/market.alternative.config.md +68 -0
- package/dist/knowledge/references/market.alternative.kind.md +32 -0
- package/dist/knowledge/references/market.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/market.buying-journey.config.md +43 -0
- package/dist/knowledge/references/market.buying-journey.stage.md +33 -0
- package/dist/knowledge/references/market.category.config.md +63 -0
- package/dist/knowledge/references/market.channel.config.md +59 -0
- package/dist/knowledge/references/market.channel.kind.md +49 -0
- package/dist/knowledge/references/market.context-block.builder.md +544 -0
- package/dist/knowledge/references/market.context-block.response.md +57 -0
- package/dist/knowledge/references/market.feature-benefit.config.md +84 -0
- package/dist/knowledge/references/market.feature-benefit.kano.md +41 -0
- package/dist/knowledge/references/market.gain.config.md +50 -0
- package/dist/knowledge/references/market.generation.response.md +108 -0
- package/dist/knowledge/references/market.icp.config.md +162 -0
- package/dist/knowledge/references/market.icp.geographic-targeting.md +57 -0
- package/dist/knowledge/references/market.inherit-from.md +74 -0
- package/dist/knowledge/references/market.is-benefit-available.md +58 -0
- package/dist/knowledge/references/market.job.config.md +48 -0
- package/dist/knowledge/references/market.message-template.config.md +86 -0
- package/dist/knowledge/references/market.objection.config.md +56 -0
- package/dist/knowledge/references/market.objection.kind.md +34 -0
- package/dist/knowledge/references/market.pain.config.md +50 -0
- package/dist/knowledge/references/market.persona.config.md +64 -0
- package/dist/knowledge/references/market.positioning.config.md +84 -0
- package/dist/knowledge/references/market.proof.config.md +48 -0
- package/dist/knowledge/references/market.proof.kind.md +34 -0
- package/dist/knowledge/references/market.references.weighted-edges.md +105 -0
- package/dist/knowledge/references/market.scoring.fit.md +215 -0
- package/dist/knowledge/references/market.snapshot.config.md +34 -0
- package/dist/knowledge/references/market.snapshot.validation.md +1171 -0
- package/dist/knowledge/references/market.tone-of-voice.config.md +80 -0
- package/dist/knowledge/references/market.trigger.config.md +45 -0
- package/dist/knowledge/references/market.trigger.kind.md +35 -0
- package/dist/knowledge/references/placement-plan.config.md +330 -0
- package/dist/knowledge/references/platform.config.application-database.md +74 -0
- package/dist/knowledge/references/platform.config.application-modules.md +30 -0
- package/dist/knowledge/references/platform.config.backing-services.md +266 -0
- package/dist/knowledge/references/platform.config.cdn.md +167 -0
- package/dist/knowledge/references/platform.config.environment.deployment.md +263 -0
- package/dist/knowledge/references/platform.config.saas.md +405 -0
- package/dist/knowledge/references/presets.models.design-system.configuration.md +59 -0
- package/dist/knowledge/references/presets.models.design-system.source-config.md +72 -0
- package/dist/knowledge/references/presets.models.labelling.sections.md +64 -0
- package/dist/knowledge/references/presets.models.material.profile-contract.md +192 -0
- package/dist/knowledge/references/presets.models.material.runtime-policy.md +60 -0
- package/dist/knowledge/references/presets.models.surface-policy.defaults.md +613 -0
- package/dist/knowledge/references/presets.models.surface-policy.md +534 -0
- package/dist/knowledge/references/presets.models.surface-variant.md +56 -0
- package/dist/knowledge/references/requirements.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +68 -0
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +100 -0
- package/dist/knowledge/references/requirements.references.conventions.md +125 -0
- package/dist/knowledge/references/requirements.snapshot.config.md +73 -0
- package/dist/knowledge/references/requirements.snapshot.validation.md +333 -0
- package/dist/knowledge/references/roadmap.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/roadmap.phase.config.md +149 -0
- package/dist/knowledge/references/roadmap.references.conventions.md +89 -0
- package/dist/knowledge/references/roadmap.snapshot.config.md +65 -0
- package/dist/knowledge/references/roadmap.snapshot.validation.md +325 -0
- package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +32 -0
- package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +38 -0
- package/dist/knowledge/references/saas.backend.billing.resolution-failure-reasons.md +45 -0
- package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +53 -0
- package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +120 -0
- package/dist/knowledge/references/saas.backend.domain-module.md +237 -0
- package/dist/knowledge/references/saas.backend.email-template.definition.md +69 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +89 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +118 -0
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +82 -0
- package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +48 -0
- package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +39 -0
- package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +67 -0
- package/dist/knowledge/references/saas.backend.pdf-template.bindings.md +52 -0
- package/dist/knowledge/references/saas.backend.pdf-template.definition.md +113 -0
- package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +75 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +994 -0
- package/dist/knowledge/references/saas.data-seeding.admin-endpoints.md +59 -0
- package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +184 -0
- package/dist/knowledge/references/saas.data-seeding.definition-input.md +95 -0
- package/dist/knowledge/references/saas.data-seeding.modes.md +72 -0
- package/dist/knowledge/references/saas.data-seeding.run-ledger.md +198 -0
- package/dist/knowledge/references/saas.data-seeding.run-status.md +35 -0
- package/dist/knowledge/references/saas.data-seeding.schedule.md +91 -0
- package/dist/knowledge/references/saas.data-seeding.scope-iteration-strategy.md +46 -0
- package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +55 -0
- package/dist/knowledge/references/saas.external-providers.document-extraction.applicability.md +26 -0
- package/dist/knowledge/references/saas.external-providers.embeddings.applicability.md +30 -0
- package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +124 -0
- package/dist/knowledge/references/saas.external-providers.llm.operation-key.md +49 -0
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +265 -0
- package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +148 -0
- package/dist/knowledge/references/saas.frontend.app-shell.hosted-components.md +145 -0
- package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +80 -0
- package/dist/knowledge/references/saas.frontend.command-menu.omnibox.md +88 -0
- package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +109 -0
- package/dist/knowledge/references/saas.frontend.component-registration.entry.md +21 -0
- package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +102 -0
- package/dist/knowledge/references/saas.frontend.composite-view.define-helper.md +31 -0
- package/dist/knowledge/references/saas.frontend.domain-module.md +31 -0
- package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +37 -0
- package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.md +172 -0
- package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.per-action-retry-loop.md +115 -0
- package/dist/knowledge/references/saas.frontend.execution-view.definition.md +172 -0
- package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.local-pane.md +109 -0
- package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.md +55 -0
- package/dist/knowledge/references/saas.frontend.execution-view.dirty-state-contract.md +151 -0
- package/dist/knowledge/references/saas.frontend.execution-view.failure-handling-contract.md +302 -0
- package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.md +89 -0
- package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.md +231 -0
- package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator.md +174 -0
- package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.md +96 -0
- package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.resolution.md +45 -0
- package/dist/knowledge/references/saas.frontend.execution-view.outcome-emission-contract.md +71 -0
- package/dist/knowledge/references/saas.frontend.execution-view.participation-and-anchor.md +80 -0
- package/dist/knowledge/references/saas.frontend.execution-view.three-zone-contract.md +147 -0
- package/dist/knowledge/references/saas.frontend.flows-actors-view.md +40 -0
- package/dist/knowledge/references/saas.frontend.form-fields.file-provider-constraints.md +80 -0
- package/dist/knowledge/references/saas.frontend.full-custom-view.definition.md +64 -0
- package/dist/knowledge/references/saas.frontend.inserted-view.identity-bindings-descriptor.md +149 -0
- package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +63 -0
- package/dist/knowledge/references/saas.frontend.quick-switcher.scope-field.md +102 -0
- package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +86 -0
- package/dist/knowledge/references/saas.frontend.related-resource-preview.md +23 -0
- package/dist/knowledge/references/saas.frontend.related-resource-sections.md +28 -0
- package/dist/knowledge/references/saas.frontend.resource-header-title.md +43 -0
- package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +215 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +531 -0
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +210 -0
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-preset-map.md +39 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +58 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +118 -0
- package/dist/knowledge/references/saas.frontend.view-definition-scope.md +42 -0
- package/dist/knowledge/references/saas.market.generation-agent.md +104 -0
- package/dist/knowledge/references/saas.models.core-resource-operation.md +86 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +395 -0
- package/dist/knowledge/references/saas.models.engine-capabilities.md +114 -0
- package/dist/knowledge/references/saas.models.error-type.md +45 -0
- package/dist/knowledge/references/saas.models.external-data-pipeline.md +162 -0
- package/dist/knowledge/references/saas.models.feature-limit-semantic.md +51 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +127 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +115 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-invocation.md +52 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-prompt-spec.md +188 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +237 -0
- package/dist/knowledge/references/saas.models.navigation.layout.md +149 -0
- package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +22 -0
- package/dist/knowledge/references/saas.models.organization-unit-narrowing-declaration.md +42 -0
- package/dist/knowledge/references/saas.models.polymorphism.optout-business-key.md +62 -0
- package/dist/knowledge/references/saas.models.polymorphism.variant-definition.md +74 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +97 -0
- package/dist/knowledge/references/saas.models.rate-limit-configuration.md +67 -0
- package/dist/knowledge/references/saas.models.relationship-handling-contract.md +30 -0
- package/dist/knowledge/references/saas.models.relationship-handling-settings.md +62 -0
- package/dist/knowledge/references/saas.models.relationship-nature-and-models.md +112 -0
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +431 -0
- package/dist/knowledge/references/saas.models.resource-config.forwarded-label.md +88 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +89 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-base.md +79 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +49 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-path.md +27 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-union.md +26 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-variant-for-key.md +62 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +124 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-relationships-buckets.md +38 -0
- package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +69 -0
- package/dist/knowledge/references/saas.models.resource-config.searchable-relation.md +89 -0
- package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +121 -0
- package/dist/knowledge/references/saas.models.resource-config.token-generation.md +145 -0
- package/dist/knowledge/references/saas.models.resource-field-identifier.md +25 -0
- package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +77 -0
- package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +58 -0
- package/dist/knowledge/references/saas.models.resource-primary-scope.md +36 -0
- package/dist/knowledge/references/saas.models.resource-relationship-access-scope.md +26 -0
- package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +100 -0
- package/dist/knowledge/references/saas.models.resource-relationship-cardinality.md +57 -0
- package/dist/knowledge/references/saas.models.resource-relationship-declaration.md +69 -0
- package/dist/knowledge/references/saas.models.resource-relationship-resolved-semantics.md +60 -0
- package/dist/knowledge/references/saas.models.resource-relationship-schema.md +172 -0
- package/dist/knowledge/references/saas.models.resource-server-instance.md +109 -0
- package/dist/knowledge/references/saas.models.resource-type.md +24 -0
- package/dist/knowledge/references/saas.models.schema-family-builder.md +242 -0
- package/dist/knowledge/references/saas.models.scope-membership.md +143 -0
- package/dist/knowledge/references/saas.models.shared-domain-module.md +36 -0
- package/dist/knowledge/references/saas.models.shared-saas-module.md +36 -0
- package/dist/knowledge/references/saas.public-runtime.contract.md +229 -0
- package/dist/knowledge/references/saas.rag.retrieval-bounds.md +106 -0
- package/dist/knowledge/references/saas.rag.retrieval-refusals.md +89 -0
- package/dist/knowledge/references/saas.rag.retrieval-request.md +130 -0
- package/dist/knowledge/references/saas.rag.retrieval-result.md +147 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +54 -0
- package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +59 -0
- package/dist/knowledge/references/saas.specifications.application-document-publication.contract.md +74 -0
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +1158 -0
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +2602 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +180 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +138 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-rating.md +47 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-article.md +49 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-blog-posting.md +62 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-breadcrumb-list.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-faq-page.md +51 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-offer.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-organization.md +48 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +59 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-review.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-website.md +46 -0
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +530 -0
- package/dist/knowledge/references/saas.specifications.composite-view-specification.md +49 -0
- package/dist/knowledge/references/saas.specifications.error-message-specification.md +92 -0
- package/dist/knowledge/references/saas.specifications.family-specifications.md +109 -0
- package/dist/knowledge/references/saas.specifications.feature-specification.md +93 -0
- package/dist/knowledge/references/saas.specifications.frontend-component-spec-factory.md +113 -0
- package/dist/knowledge/references/saas.specifications.frontend-component-spec-model.md +366 -0
- package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +41 -0
- package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +1978 -0
- package/dist/knowledge/references/saas.specifications.resource-pdf-template-spec.md +58 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-code-handling.md +49 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +156 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +171 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-frontend-config-type.md +54 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +171 -0
- package/dist/knowledge/references/saas.website.astro.bridge.md +262 -0
- package/dist/knowledge/references/saas.website.astro.head-renderer.md +271 -0
- package/dist/knowledge/references/saas.website.astro.headers-renderer.md +41 -0
- package/dist/knowledge/references/saas.website.astro.i18n-helper.md +121 -0
- package/dist/knowledge/references/saas.website.astro.label-key-collector.md +117 -0
- package/dist/knowledge/references/saas.website.astro.label-loader.md +377 -0
- package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +46 -0
- package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +90 -0
- package/dist/knowledge/references/saas.website.astro.robots-renderer.md +174 -0
- package/dist/knowledge/references/saas.website.astro.runtime-helper.md +187 -0
- package/dist/knowledge/references/saas.website.astro.site-context.md +141 -0
- package/dist/knowledge/references/saas.website.astro.sitemap-coverage.md +188 -0
- package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +174 -0
- package/dist/knowledge/references/saas.website.blog.bridge.md +396 -0
- package/dist/knowledge/references/saas.website.blog.collection-config.md +180 -0
- package/dist/knowledge/references/saas.website.blog.frontmatter.md +116 -0
- package/dist/knowledge/references/saas.website.blog.head-renderer.md +292 -0
- package/dist/knowledge/references/saas.website.blog.mdx-provider.md +100 -0
- package/dist/knowledge/references/saas.website.blog.post-renderer.md +291 -0
- package/dist/knowledge/references/saas.website.design-tokens.bundle.md +29 -0
- package/dist/knowledge/references/saas.website.design-tokens.colors.md +64 -0
- package/dist/knowledge/references/saas.website.design-tokens.radius.md +38 -0
- package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +98 -0
- package/dist/knowledge/references/saas.website.factories.define-section.md +128 -0
- package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +36 -0
- package/dist/knowledge/references/saas.website.label-keys.format.md +67 -0
- package/dist/knowledge/references/saas.website.label-pack.validator.md +206 -0
- package/dist/knowledge/references/saas.website.page-layout.component.md +217 -0
- package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +47 -0
- package/dist/knowledge/references/saas.website.page-manifest.route-path.md +49 -0
- package/dist/knowledge/references/saas.website.page-manifest.schema.md +186 -0
- package/dist/knowledge/references/saas.website.page-manifest.seo.md +46 -0
- package/dist/knowledge/references/saas.website.page.context.md +57 -0
- package/dist/knowledge/references/saas.website.primitives.button.md +123 -0
- package/dist/knowledge/references/saas.website.primitives.heading.md +103 -0
- package/dist/knowledge/references/saas.website.primitives.image.md +103 -0
- package/dist/knowledge/references/saas.website.primitives.internal-button.md +151 -0
- package/dist/knowledge/references/saas.website.primitives.internal-link.md +193 -0
- package/dist/knowledge/references/saas.website.primitives.link.md +78 -0
- package/dist/knowledge/references/saas.website.primitives.text.md +82 -0
- package/dist/knowledge/references/saas.website.refs.page.md +56 -0
- package/dist/knowledge/references/saas.website.refs.section.md +57 -0
- package/dist/knowledge/references/saas.website.root-config.navigation.md +37 -0
- package/dist/knowledge/references/saas.website.root-config.schema.md +192 -0
- package/dist/knowledge/references/saas.website.root-config.seo.md +98 -0
- package/dist/knowledge/references/saas.website.routing.localized-path.md +84 -0
- package/dist/knowledge/references/saas.website.runtime.context.md +174 -0
- package/dist/knowledge/references/saas.website.section.component.md +138 -0
- package/dist/knowledge/references/saas.website.section.context.md +63 -0
- package/dist/knowledge/references/saas.website.sections.category-enum.md +72 -0
- package/dist/knowledge/references/saas.website.sections.definition-schema.md +121 -0
- package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +37 -0
- package/dist/knowledge/references/saas.website.seo.robots-config.md +106 -0
- package/dist/knowledge/references/saas.website.seo.sitemap-config.md +73 -0
- package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +71 -0
- package/dist/knowledge/references/saas.website.use-label-by-key.hook.md +45 -0
- package/dist/knowledge/references/saas.website.use-label.hook.md +82 -0
- package/dist/knowledge/references/saas.website.use-page.hook.md +30 -0
- package/dist/knowledge/references/saas.website.use-runtime.hook.md +36 -0
- package/dist/knowledge/references/saas.website.use-section.hook.md +30 -0
- package/dist/knowledge/references/saas.website.use-tokens.hook.md +32 -0
- package/dist/knowledge/references/vision.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/vision.constraint.config.md +66 -0
- package/dist/knowledge/references/vision.idea.config.md +45 -0
- package/dist/knowledge/references/vision.mission.config.md +46 -0
- package/dist/knowledge/references/vision.problem.config.md +51 -0
- package/dist/knowledge/references/vision.references.conventions.md +115 -0
- package/dist/knowledge/references/vision.snapshot.config.md +85 -0
- package/dist/knowledge/references/vision.snapshot.validation.md +226 -0
- package/dist/knowledge/references/vision.success-criterion.config.md +60 -0
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +550 -0
- package/dist/knowledge/references/zod.decorators.conditional-visibility.md +104 -0
- package/dist/knowledge/references/zod.decorators.data-categories.md +197 -0
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +436 -0
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +174 -0
- package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +101 -0
- package/dist/knowledge/references/zod.decorators.field-spec-params.md +317 -0
- package/dist/knowledge/references/zod.decorators.file-generation.md +36 -0
- package/dist/knowledge/references/zod.decorators.file-rag-source.md +56 -0
- package/dist/knowledge/references/zod.decorators.file-schema.md +319 -0
- package/dist/knowledge/references/zod.decorators.foreign-key-display-mode.md +83 -0
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +459 -0
- package/dist/knowledge/references/zod.decorators.primitive-ui.md +123 -0
- package/dist/knowledge/references/zod.decorators.rag-source.md +164 -0
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +122 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +152 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +314 -0
- package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +529 -0
- package/dist/knowledge/references/zod.factories.bigdecimal.md +155 -0
- package/dist/knowledge/references/zod.factories.code.md +127 -0
- package/dist/knowledge/references/zod.factories.duration.md +246 -0
- package/dist/knowledge/references/zod.factories.money.md +166 -0
- package/dist/knowledge/references/zod.factories.phone.md +88 -0
- package/dist/knowledge/references/zod.factories.range.md +174 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +15 -0
- package/dist/knowledge/registries/framework-topics.json +5212 -0
- package/dist/knowledge/registries/playbooks.json +488 -0
- package/dist/knowledge/registries/source-tags.json +7664 -0
- package/dist/knowledge/rules/resource-schema-awareness.md +77 -0
- package/dist/knowledge/skills/INDEX.md +349 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +415 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/examples/domain-use-case-and-admin-task.example.md +49 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +52 -0
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +218 -0
- package/dist/knowledge/skills/application-database-migrations/references/framework-application-database-api.md +84 -0
- package/dist/knowledge/skills/application-database-migrations/references/framework-migration-change-risk-api.md +37 -0
- package/dist/knowledge/skills/application-database-migrations/references/migration-refusals.md +64 -0
- package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +323 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +84 -0
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +324 -0
- package/dist/knowledge/skills/backend-addon-wiring/references/backend-di-routing.md +7 -0
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +276 -0
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +374 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +118 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +107 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +134 -0
- package/dist/knowledge/skills/backend-custom-operation/references/operation-file-conventions.md +10 -0
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +192 -0
- package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +55 -0
- package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-asset-api.md +184 -0
- package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +279 -0
- package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +346 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +160 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +518 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +158 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +95 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-publication-contract.md +100 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +1210 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +40 -0
- package/dist/knowledge/skills/config-app-shell/SKILL.md +698 -0
- package/dist/knowledge/skills/config-app-shell/references/app-shell-surfaces.md +5 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +415 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +170 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +212 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-quick-switcher-scope-field-api.md +178 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +424 -0
- package/dist/knowledge/skills/config-design-system/references/design-system-file.md +10 -0
- package/dist/knowledge/skills/config-design-system/references/framework-design-system-configuration-api.md +77 -0
- package/dist/knowledge/skills/config-design-system/references/framework-material-profile-api.md +200 -0
- package/dist/knowledge/skills/config-design-system/references/framework-material-runtime-policy-api.md +68 -0
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +1212 -0
- package/dist/knowledge/skills/config-design-system/references/surface-policy-authoring.md +92 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +249 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +152 -0
- package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +5 -0
- package/dist/knowledge/skills/config-saas/SKILL.md +209 -0
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +221 -0
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +408 -0
- package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +9 -0
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +183 -0
- package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +40 -0
- package/dist/knowledge/skills/configure-billing/SKILL.md +261 -0
- package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +90 -0
- package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +122 -0
- package/dist/knowledge/skills/configure-billing/references/example-provider-contribution-and-backend-config.md +48 -0
- package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +69 -0
- package/dist/knowledge/skills/configure-billing/references/framework-billing-resolution-failure-api.md +57 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +439 -0
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +9 -0
- package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +72 -0
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +62 -0
- package/dist/knowledge/skills/email-labels-authoring/SKILL.md +64 -0
- package/dist/knowledge/skills/email-template-authoring/SKILL.md +62 -0
- package/dist/knowledge/skills/engine-component-registration/SKILL.md +257 -0
- package/dist/knowledge/skills/engine-component-registration/references/component-registration-file.md +7 -0
- package/dist/knowledge/skills/engine-component-registration/references/framework-component-registration-api.md +24 -0
- package/dist/knowledge/skills/engine-product-definitions/SKILL.md +429 -0
- package/dist/knowledge/skills/engine-product-definitions/references/framework-engine-product-definitions-api.md +287 -0
- package/dist/knowledge/skills/engine-product-definitions/references/product-registry-scope.md +5 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +491 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +227 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-named-a2a-agents-contract.md +143 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +368 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +226 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +208 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +286 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +376 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +262 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +130 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-prompt-spec-api.md +214 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +195 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/operation-key-selection.md +60 -0
- package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +237 -0
- package/dist/knowledge/skills/frontend-cdn-publish/references/cloudflare-and-operator-setup.md +56 -0
- package/dist/knowledge/skills/frontend-cdn-publish/references/framework-cdn-config-api.md +176 -0
- package/dist/knowledge/skills/i18n-label-generation/SKILL.md +261 -0
- package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +67 -0
- package/dist/knowledge/skills/i18n-label-generation/references/label-placement.md +7 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +269 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +67 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/references/i18n-routing.md +9 -0
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +245 -0
- package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +67 -0
- package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +17 -0
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +646 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-application-database-api.md +77 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +282 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +265 -0
- package/dist/knowledge/skills/infra-environment-config/references/infra-config-files.md +7 -0
- package/dist/knowledge/skills/journey-approve/SKILL.md +43 -0
- package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +42 -0
- package/dist/knowledge/skills/journey-next/SKILL.md +42 -0
- package/dist/knowledge/skills/journey-report/SKILL.md +43 -0
- package/dist/knowledge/skills/journey-run/SKILL.md +55 -0
- package/dist/knowledge/skills/journey-status/SKILL.md +50 -0
- package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +370 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/initialization-recovery-recipe.md +50 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +409 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +247 -0
- package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +474 -0
- package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +139 -0
- package/dist/knowledge/skills/market-alternatives/SKILL.md +543 -0
- package/dist/knowledge/skills/market-authoring-overview/SKILL.md +354 -0
- package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +138 -0
- package/dist/knowledge/skills/market-authoring-overview/references/framework-market-snapshot-api.md +129 -0
- package/dist/knowledge/skills/market-category/SKILL.md +290 -0
- package/dist/knowledge/skills/market-channels/SKILL.md +361 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +2752 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +2443 -0
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +1484 -0
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +1230 -0
- package/dist/knowledge/skills/market-icp/SKILL.md +625 -0
- package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +352 -0
- package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +415 -0
- package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1439 -0
- package/dist/knowledge/skills/market-persona/SKILL.md +407 -0
- package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +392 -0
- package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +97 -0
- package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +665 -0
- package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +620 -0
- package/dist/knowledge/skills/market-scoring-interpretation/references/framework-scoring-api.md +291 -0
- package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1706 -0
- package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1228 -0
- package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +260 -0
- package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +579 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +318 -0
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +544 -0
- package/dist/knowledge/skills/module-registration/SKILL.md +212 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +366 -0
- package/dist/knowledge/skills/module-registration/references/registry-files.md +9 -0
- package/dist/knowledge/skills/module-relationships/SKILL.md +523 -0
- package/dist/knowledge/skills/module-relationships/references/cross-resource-fk-checklist.md +7 -0
- package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +738 -0
- package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +174 -0
- package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-api.md +203 -0
- package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-spec-api.md +62 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +239 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-file-provider-constraints-api.md +90 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +50 -0
- package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +652 -0
- package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +182 -0
- package/dist/knowledge/skills/rate-limit-authoring/references/scope-key-and-bucket-conventions.md +137 -0
- package/dist/knowledge/skills/resource-add-field/SKILL.md +272 -0
- package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +153 -0
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +845 -0
- package/dist/knowledge/skills/resource-add-module/SKILL.md +322 -0
- package/dist/knowledge/skills/resource-add-module/references/framework-new-module-wiring-api.md +67 -0
- package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +15 -0
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +222 -0
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +540 -0
- package/dist/knowledge/skills/resource-add-resource/references/scaffold-surfaces-checklist.md +25 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +370 -0
- package/dist/knowledge/skills/resource-config-wiring/references/config-change-routing.md +11 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +622 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +248 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +1769 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +1209 -0
- package/dist/knowledge/skills/resource-custom-view/SKILL.md +228 -0
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +693 -0
- package/dist/knowledge/skills/resource-external-data/SKILL.md +349 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +187 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +261 -0
- package/dist/knowledge/skills/resource-external-data/references/lane-selection.md +49 -0
- package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +43 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +308 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-named-mcp-servers-contract.md +166 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +63 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +77 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +90 -0
- package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +424 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/corpus-field-selection.md +90 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +261 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-file-rag-source-api.md +117 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +597 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +181 -0
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +318 -0
- package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +132 -0
- package/dist/knowledge/skills/resource-schema-authoring/examples/basic-resource-schema.example.md +62 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +63 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +70 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +559 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +245 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-polymorphic-resources-api.md +147 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +247 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +164 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +327 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +1286 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +1080 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/polymorphic-per-scope-resources.md +75 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/schema-variants-and-discriminators.md +62 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +69 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +45 -0
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +389 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-conditional-visibility-api.md +106 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +176 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +103 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-foreign-key-ui-api.md +97 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +839 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +461 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +125 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +245 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +302 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/ui-layer-boundaries.md +13 -0
- package/dist/knowledge/skills/seeding-authoring/SKILL.md +569 -0
- package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +154 -0
- package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +176 -0
- package/dist/knowledge/skills/seeding-operations/SKILL.md +505 -0
- package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +337 -0
- package/dist/knowledge/skills/seeding-operations/references/data-seeding-cron-scheduler.md +171 -0
- package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +662 -0
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +134 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +65 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +127 -0
- package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +726 -0
- package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +242 -0
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +362 -0
- package/dist/knowledge/skills/spec-companion-exports/references/companion-export-checklist.md +8 -0
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +533 -0
- package/dist/knowledge/skills/spec-component-update/SKILL.md +315 -0
- package/dist/knowledge/skills/spec-component-update/references/component-spec-props.md +8 -0
- package/dist/knowledge/skills/spec-component-update/references/framework-frontend-component-spec-api.md +481 -0
- package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +283 -0
- package/dist/knowledge/skills/spec-composite-view-update/references/composite-spec-sections.md +5 -0
- package/dist/knowledge/skills/spec-composite-view-update/references/framework-composite-view-specification-api.md +51 -0
- package/dist/knowledge/skills/spec-family-update/SKILL.md +300 -0
- package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +13 -0
- package/dist/knowledge/skills/spec-family-update/references/framework-error-message-specifications-api.md +108 -0
- package/dist/knowledge/skills/spec-family-update/references/framework-family-specifications-api.md +111 -0
- package/dist/knowledge/skills/spec-feature-update/SKILL.md +306 -0
- package/dist/knowledge/skills/spec-feature-update/references/feature-spec-scope.md +5 -0
- package/dist/knowledge/skills/spec-feature-update/references/framework-feature-specification-api.md +95 -0
- package/dist/knowledge/skills/spec-resource-update/SKILL.md +220 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +319 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +2610 -0
- package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +12 -0
- package/dist/knowledge/skills/spec-update-after-change/SKILL.md +195 -0
- package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +173 -0
- package/dist/knowledge/skills/spec-update-after-change/references/spec-maintenance-by-surface.md +33 -0
- package/dist/knowledge/skills/spec-update-after-change/references/surface-to-spec-routing.md +14 -0
- package/dist/knowledge/skills/views-add-composite-view/SKILL.md +259 -0
- package/dist/knowledge/skills/views-add-composite-view/references/composite-view-routing.md +10 -0
- package/dist/knowledge/skills/views-add-composite-view/references/framework-inserted-view-identity-api.md +151 -0
- package/dist/knowledge/skills/views-add-custom-view/SKILL.md +225 -0
- package/dist/knowledge/skills/views-add-custom-view/references/custom-view-routing.md +10 -0
- package/dist/knowledge/skills/views-add-custom-view/references/framework-view-scope-and-full-custom-api.md +107 -0
- package/dist/knowledge/skills/views-app-level/SKILL.md +201 -0
- package/dist/knowledge/skills/views-app-level/references/app-level-views-routing.md +9 -0
- package/dist/knowledge/skills/views-app-level/references/framework-view-scope-and-full-custom-api.md +107 -0
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +264 -0
- package/dist/knowledge/skills/views-chart-authoring/references/chart-view-checklist.md +7 -0
- package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +82 -0
- package/dist/knowledge/skills/views-chart-authoring/references/framework-inserted-view-identity-api.md +152 -0
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +302 -0
- package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +23 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +133 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-inserted-view-identity-api.md +152 -0
- package/dist/knowledge/skills/views-execution-authoring/SKILL.md +209 -0
- package/dist/knowledge/skills/views-execution-authoring/references/execution-view-checklist.md +7 -0
- package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +389 -0
- package/dist/knowledge/skills/views-execution-authoring/references/framework-inserted-view-identity-api.md +152 -0
- package/dist/knowledge/skills/website-anonymous-session/SKILL.md +444 -0
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +587 -0
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1426 -0
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +553 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +52 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +357 -0
- package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +511 -0
- package/dist/knowledge/skills/website-factory-advanced/SKILL.md +376 -0
- package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +304 -0
- package/dist/knowledge/skills/website-label-pack/SKILL.md +390 -0
- package/dist/knowledge/skills/website-layout-overrides/SKILL.md +461 -0
- package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +264 -0
- package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +414 -0
- package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +366 -0
- package/dist/knowledge/skills/website-page-authoring/SKILL.md +420 -0
- package/dist/knowledge/skills/website-page-variants/SKILL.md +256 -0
- package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +302 -0
- package/dist/knowledge/skills/website-section-contact/SKILL.md +950 -0
- package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-cta/SKILL.md +822 -0
- package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-faq/SKILL.md +917 -0
- package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +878 -0
- package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +895 -0
- package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +814 -0
- package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-hero/SKILL.md +944 -0
- package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +583 -0
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +934 -0
- package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +912 -0
- package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +624 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +633 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +193 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +790 -0
- package/dist/knowledge/topic-index.json +17510 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -0
- package/dist/tsconfig.tsbuildinfo +1 -0
- package/package.json +49 -0
|
@@ -0,0 +1,2610 @@
|
|
|
1
|
+
# Framework — resource specification contracts (saas-specifications)
|
|
2
|
+
|
|
3
|
+
Source-backed excerpts for operation/variant prose, frontend aspect distillation, spec `frontend` prose and config types, `codeHandling`, `ResourceSpecificationConfig`, and `resourceSpecification()` factory.
|
|
4
|
+
|
|
5
|
+
## Import Origins
|
|
6
|
+
|
|
7
|
+
- `@wildo-ai/saas-specifications`
|
|
8
|
+
|
|
9
|
+
## Source Excerpts
|
|
10
|
+
|
|
11
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
*
|
|
15
|
+
* Companion-facing semantic prose for operations and variants (`resourceSpecification().operations`).
|
|
16
|
+
*
|
|
17
|
+
* **Per-variant** semantics (`ResourceOperationVariantSpecification`):
|
|
18
|
+
* Provides sparse overlays for an operation's business prose and, when an
|
|
19
|
+
* HTTP response shape genuinely differs, its payload examples. URLs, DTO
|
|
20
|
+
* shape, and authorization rules remain structural contracts; prose explains
|
|
21
|
+
* what the operation accomplishes in business terms, while examples make the
|
|
22
|
+
* concrete transport representation understandable.
|
|
23
|
+
*
|
|
24
|
+
* **Per-operation** map types (`ResourceOperationSpecification`, maps) layer
|
|
25
|
+
* shared operation meaning plus optional named variants (`admin`, `summary`,
|
|
26
|
+
* `context`, …) aligned with the resource configuration vocabulary.
|
|
27
|
+
*
|
|
28
|
+
* **HTTP documentation** fields on `ResourceOperationSpecification`
|
|
29
|
+
* (`responseStatuses`, `errorScenarios`, `idempotent`, `rateLimitNote`,
|
|
30
|
+
* `examples`) carry the transport-level outcomes the OpenAPI generator emits
|
|
31
|
+
* as `responses` / `examples` / `x-idempotent`. Response outcomes are
|
|
32
|
+
* per-operation. Base examples apply to every variant unless a variant owns a
|
|
33
|
+
* complete replacement, preventing a full DTO example from leaking into a
|
|
34
|
+
* context or summary response. HTTP-only fields are intentionally excluded
|
|
35
|
+
* from frontend-view specs, which are not HTTP operations.
|
|
36
|
+
*/
|
|
37
|
+
export interface ResourceOperationVariantSpecification {
|
|
38
|
+
/** Business intent of the operation when this variant differs from the base operation. */
|
|
39
|
+
purpose?: string;
|
|
40
|
+
/** Observable business result once the operation succeeds. */
|
|
41
|
+
outcome?: string;
|
|
42
|
+
/** Guidance about when this operation is the right choice. */
|
|
43
|
+
whenToUse?: string;
|
|
44
|
+
/** Relative weight of this operation in the resource understanding. */
|
|
45
|
+
importance?: FieldSemanticImportance;
|
|
46
|
+
/**
|
|
47
|
+
* Override the resource-level label {@link LabelAudience} for THIS operation's
|
|
48
|
+
* generated labels. Use when a mostly-end-user resource exposes an admin-only
|
|
49
|
+
* operation (or vice-versa) so its copy adopts the right register without
|
|
50
|
+
* reclassifying the whole resource. Omit to inherit the resource's `audience`.
|
|
51
|
+
*/
|
|
52
|
+
audienceOverride?: LabelAudience;
|
|
53
|
+
/**
|
|
54
|
+
* Variant-specific OpenAPI examples. When present, these REPLACE the base
|
|
55
|
+
* operation `examples` for this variant; they never merge. Use this where a
|
|
56
|
+
* context or summary response has a different schema from the default path.
|
|
57
|
+
*/
|
|
58
|
+
examples?: ResourceOperationExampleSpecification[];
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Variant map for one operation.
|
|
63
|
+
*
|
|
64
|
+
* `default` represents the default/no-explicit-variant path. Named variant keys
|
|
65
|
+
* (`admin`, `summary`, `context`, `internal`, ...) mirror the authored
|
|
66
|
+
* operation-variant vocabulary instead of flattening them into synthetic tuples.
|
|
67
|
+
*/
|
|
68
|
+
export type ResourceOperationSpecificationVariants = Record<string, ResourceOperationVariantSpecification | undefined> & {
|
|
69
|
+
default?: ResourceOperationVariantSpecification;
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Frontend-view variants preserve business semantics but deliberately exclude
|
|
74
|
+
* HTTP examples: a frontend view is not an API operation and must not become a
|
|
75
|
+
* second authoring path for generated OpenAPI payloads.
|
|
76
|
+
*/
|
|
77
|
+
export type ResourceFrontendViewSpecificationVariants = Record<
|
|
78
|
+
string,
|
|
79
|
+
Omit<ResourceOperationVariantSpecification, 'examples'> | undefined
|
|
80
|
+
> & {
|
|
81
|
+
default?: Omit<ResourceOperationVariantSpecification, 'examples'>;
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Import-oriented metadata for the email fired by a resource operation.
|
|
86
|
+
*
|
|
87
|
+
* Lets downstream transposer/code-generation layers point at the real event
|
|
88
|
+
* payload schema without re-reading the resource's backend code.
|
|
89
|
+
*/
|
|
90
|
+
export interface ResourceOperationEmailSpecificationCodeHandling {
|
|
91
|
+
/** Public Zod schema symbol that describes the event payload of the email. */
|
|
92
|
+
eventDataSchemaSymbol?: CodeSymbolRef;
|
|
93
|
+
/** Public TypeScript type symbol when the payload type is split from its Zod schema. */
|
|
94
|
+
eventDataTypeSymbol?: CodeSymbolRef;
|
|
95
|
+
/** Extra supporting symbols (builders, renderers) that transposer prompts need. */
|
|
96
|
+
supportingSymbols?: CodeSymbolRef[];
|
|
97
|
+
/** Companion/transposer caveats that must survive serialization. */
|
|
98
|
+
notes?: string[];
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Semantic overlay for ONE email delivery fired by a resource operation.
|
|
103
|
+
*
|
|
104
|
+
* Models the engine fan-out faithfully: every entry in the runtime
|
|
105
|
+
* `userNotifications[]` array with `channel === EMAIL` is one delivery, and
|
|
106
|
+
* the runtime constructs a distinct template-ref path for each
|
|
107
|
+
* `(variantKey, targetType, customNotificationRef)` combination through the
|
|
108
|
+
* notifications dispatcher (`email.{resourceId}.{op}.{variant?}.{target-kebab}_{customRef?}`).
|
|
109
|
+
*
|
|
110
|
+
* Authoring sites declare one delivery per such combination so:
|
|
111
|
+
* - companion prompts know exactly how many template files exist for the operation,
|
|
112
|
+
* - translators can author per-delivery overrides when the audience changes the copy,
|
|
113
|
+
* - transposers can compute the runtime template-ref path from the spec without
|
|
114
|
+
* re-reading the resource configuration code.
|
|
115
|
+
*
|
|
116
|
+
* The parent `ResourceOperationEmailSpecification` carries shared semantics
|
|
117
|
+
* (purpose, tone, default text slots, event data); per-delivery overrides
|
|
118
|
+
* layer on top via `purposeOverride`, `textSlotsOverrides`,
|
|
119
|
+
* `additionalBusinessConstraints`. Omit overrides when the delivery shares
|
|
120
|
+
* the parent copy verbatim — that is the common case.
|
|
121
|
+
*/
|
|
122
|
+
export interface ResourceOperationEmailDeliverySpecification {
|
|
123
|
+
/**
|
|
124
|
+
* Audience description: who receives this delivery and why. Required —
|
|
125
|
+
* the deliveries axis exists specifically to distinguish audiences (creator
|
|
126
|
+
* vs assignee vs admin recipient, …), so an undocumented audience defeats
|
|
127
|
+
* the purpose of fanning out.
|
|
128
|
+
*/
|
|
129
|
+
audience: string;
|
|
130
|
+
/**
|
|
131
|
+
* Target type from the runtime `UserNotificationDefinition.target` (see
|
|
132
|
+
* `CoreUserNotificationTarget` — `USERS_CUSTOM`, `USER_SELF`,
|
|
133
|
+
* `ORGANIZATION_USERS`, …). The dispatcher kebab-cases this and appends
|
|
134
|
+
* it to the template-ref path, so spec authors must echo the exact runtime
|
|
135
|
+
* target so the computed path stays truthful.
|
|
136
|
+
*/
|
|
137
|
+
targetRef: CoreUserNotificationTarget | (string & {});
|
|
138
|
+
/**
|
|
139
|
+
* Operation variant this delivery belongs to. `undefined` means the default
|
|
140
|
+
* variant (no `variantKey` segment in the runtime path). Maps to
|
|
141
|
+
* `variantKey` on the runtime variant when present.
|
|
142
|
+
*/
|
|
143
|
+
variantRef?: string;
|
|
144
|
+
/**
|
|
145
|
+
* Distinguishes deliveries when the same `(variantRef, targetRef)` fires
|
|
146
|
+
* multiple emails. Maps 1:1 to `customNotificationRef` on the runtime
|
|
147
|
+
* `UserNotificationDefinition`. Required by the engine when more than one
|
|
148
|
+
* `USERS_CUSTOM` notification appears in the same operation (to make the
|
|
149
|
+
* template paths unique); the spec validator mirrors that contract.
|
|
150
|
+
*/
|
|
151
|
+
customDeliveryRef?: string;
|
|
152
|
+
/**
|
|
153
|
+
* Stable `SystemEmailTemplateRef` THIS delivery resolves to, when the
|
|
154
|
+
* runtime template path corresponds to an entry registered in
|
|
155
|
+
* `SystemEmailTemplateRegistry` (system-level emails such as
|
|
156
|
+
* `WELCOME_EMAIL`, `ORGANIZATION_INVITATION`, …). Use it to cross-link a
|
|
157
|
+
* resource-initiated trigger to its authored
|
|
158
|
+
* `SystemEmailTemplateSpecification` overlay in companion prompts.
|
|
159
|
+
*
|
|
160
|
+
* Lives per-delivery (not on `codeHandling`) because the runtime
|
|
161
|
+
* template-ref path is per-delivery: every authored
|
|
162
|
+
* `(variantRef, targetRef, customDeliveryRef)` triple resolves to ONE
|
|
163
|
+
* concrete template, so each delivery either points at a registered
|
|
164
|
+
* `SystemEmailTemplateRef` or — for resource-local templates that live
|
|
165
|
+
* outside `SystemEmailTemplateRegistry` (e.g. Your Application
|
|
166
|
+
* `email.todos.change_status.users-custom_notify-creator`) — leaves the
|
|
167
|
+
* field undefined.
|
|
168
|
+
*
|
|
169
|
+
* Cross-validated at module load against `SystemEmailTemplateRegistry` so
|
|
170
|
+
* a typo or stale ref fails closed instead of leaking a dangling cross-
|
|
171
|
+
* link into companion prompts. Typed as the enum to give authors
|
|
172
|
+
* autocomplete and eliminate the silent-string-identity anti-pattern.
|
|
173
|
+
*/
|
|
174
|
+
systemEmailTemplateRef?: SystemEmailTemplateRef;
|
|
175
|
+
/**
|
|
176
|
+
* Optional per-delivery overrides for translatable text slots. When a key
|
|
177
|
+
* is present here, it replaces the parent `textSlots[key]` for THIS
|
|
178
|
+
* delivery only (e.g., creator and assignee share the parent subject
|
|
179
|
+
* normally, but the admin variant for the creator uses a different one).
|
|
180
|
+
* Omit entirely when the delivery uses the parent copy verbatim.
|
|
181
|
+
*/
|
|
182
|
+
textSlotsOverrides?: TranslationSlotSpecificationMap;
|
|
183
|
+
/**
|
|
184
|
+
* Per-delivery override for `purpose` when this delivery has its own intent
|
|
185
|
+
* distinct from the parent (e.g., the admin variant explains a managerial
|
|
186
|
+
* intervention rather than a self-progress signal). Falls back to the
|
|
187
|
+
* parent `purpose` when omitted.
|
|
188
|
+
*/
|
|
189
|
+
purposeOverride?: string;
|
|
190
|
+
/**
|
|
191
|
+
* Domain/compliance caveats that apply to THIS delivery only, layered on
|
|
192
|
+
* top of the parent `businessConstraints` (which apply to all deliveries).
|
|
193
|
+
*/
|
|
194
|
+
additionalBusinessConstraints?: string[];
|
|
195
|
+
/** Companion/transposer caveats specific to this delivery. */
|
|
196
|
+
notes?: string[];
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Semantic overlay for the email fired by a resource operation.
|
|
201
|
+
*
|
|
202
|
+
* Follows the same authoring shape as `SystemEmailTemplateSpecification`:
|
|
203
|
+
* `purpose` and `tone` are plain authoring prose, while every translatable
|
|
204
|
+
* fragment (subject, previewText, ctaLabel, heading, body, …) lives inside
|
|
205
|
+
* `textSlots`. `eventData` documents the meaning of the payload used to render
|
|
206
|
+
* the email so translators know which runtime values will land in each slot.
|
|
207
|
+
*
|
|
208
|
+
* A resource-initiated email is always anchored to its operation: the same
|
|
209
|
+
* action decides what is sent, to whom, and why, so the companion resolves the
|
|
210
|
+
* wording through the operation spec instead of a parallel family.
|
|
211
|
+
*
|
|
212
|
+
* **Engine-parity contract for `deliveries`**. The runtime fans out one email
|
|
213
|
+
* per entry in `userNotifications[]` with `channel === EMAIL`, computing a
|
|
214
|
+
* distinct template-ref path per `(variantKey, target, customNotificationRef)`
|
|
215
|
+
* combination. The spec layer mirrors this faithfully: every such runtime
|
|
216
|
+
* delivery must be authored as one entry in `deliveries`, so the spec is
|
|
217
|
+
* never silent about a real runtime template path. A single-delivery email
|
|
218
|
+
* still needs one `deliveries` entry — the array is required so the engine
|
|
219
|
+
* fan-out semantics are explicit at every authoring site, not implicit in
|
|
220
|
+
* the absence of the field.
|
|
221
|
+
*/
|
|
222
|
+
export interface ResourceOperationEmailSpecification {
|
|
223
|
+
/** Why this operation fires an email (shared intent across all deliveries). */
|
|
224
|
+
purpose: string;
|
|
225
|
+
/** Expected voice/posture for the generated copy (urgent, reassuring, informational, ...). */
|
|
226
|
+
tone: string;
|
|
227
|
+
/** Situations where this email must be sent alongside the operation. */
|
|
228
|
+
useWhen?: string;
|
|
229
|
+
/** Situations where this email should not fire (e.g. reassignment to the same user). */
|
|
230
|
+
avoidWhen?: string;
|
|
231
|
+
/**
|
|
232
|
+
* Translatable text slots for the email (`subject`, `previewText`,
|
|
233
|
+
* `ctaLabel`, or any template-specific named slot) with per-slot meaning
|
|
234
|
+
* for translators. `subject` is required because every transactional email
|
|
235
|
+
* needs a subject line. Per-delivery overrides live on each
|
|
236
|
+
* `deliveries[i].textSlotsOverrides`.
|
|
237
|
+
*/
|
|
238
|
+
textSlots: TranslationSlotSpecificationMap;
|
|
239
|
+
/** Meaning of the event payload this email renders with (shared across deliveries). */
|
|
240
|
+
eventData?: TranslationSlotSpecification;
|
|
241
|
+
/** Domain/compliance caveats that matter beyond the operation's own constraints. */
|
|
242
|
+
businessConstraints?: string[];
|
|
243
|
+
/**
|
|
244
|
+
* Explicit fan-out: one entry per runtime `userNotifications[]` email
|
|
245
|
+
* delivery. At least one entry is required when an `email` block is
|
|
246
|
+
* authored — see the JSDoc on the parent interface for the engine-parity
|
|
247
|
+
* rationale. The validator enforces uniqueness on
|
|
248
|
+
* `(variantRef, targetRef, customDeliveryRef)` triples and rejects
|
|
249
|
+
* duplicates that would compute the same runtime template-ref path.
|
|
250
|
+
*/
|
|
251
|
+
deliveries: ResourceOperationEmailDeliverySpecification[];
|
|
252
|
+
/** Import-oriented coding/transposition metadata. */
|
|
253
|
+
codeHandling?: ResourceOperationEmailSpecificationCodeHandling;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* Import-oriented metadata for the notification fired by a resource operation.
|
|
258
|
+
*/
|
|
259
|
+
export interface ResourceOperationNotificationSpecificationCodeHandling {
|
|
260
|
+
/**
|
|
261
|
+
* Public enum exposing the channel vocabulary that each
|
|
262
|
+
* `deliveries[i].channelRef` is drawn from (for example
|
|
263
|
+
* `CoreUserNotificationChannel`). Custom channels remain expressible as raw
|
|
264
|
+
* strings on `deliveries[i].channelRef`, but declaring the owning enum lets
|
|
265
|
+
* transposer layers import the canonical members when generating
|
|
266
|
+
* notification dispatch code.
|
|
267
|
+
*/
|
|
268
|
+
channelEnum?: CodeSymbolRef;
|
|
269
|
+
/** Public Zod schema symbol describing the notification event payload. */
|
|
270
|
+
eventDataSchemaSymbol?: CodeSymbolRef;
|
|
271
|
+
/** Public TypeScript type symbol when the payload type is split from its Zod schema. */
|
|
272
|
+
eventDataTypeSymbol?: CodeSymbolRef;
|
|
273
|
+
/** Extra supporting symbols that transposer prompts need. */
|
|
274
|
+
supportingSymbols?: CodeSymbolRef[];
|
|
275
|
+
/** Companion/transposer caveats that must survive serialization. */
|
|
276
|
+
notes?: string[];
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* Semantic overlay for ONE in-app notification delivery fired by a resource
|
|
281
|
+
* operation.
|
|
282
|
+
*
|
|
283
|
+
* Models the engine fan-out faithfully: every entry in the runtime
|
|
284
|
+
* `userNotifications[]` array whose `channel` is NOT `EMAIL` is one in-app
|
|
285
|
+
* notification delivery (FRONT_END_SUCCESS toast for the actor, WEBSOCKET push
|
|
286
|
+
* to the activity feed, SMS / PUSH when implemented, …). Each delivery is
|
|
287
|
+
* its own (target, channel) pair at runtime; the spec layer mirrors this so
|
|
288
|
+
* companion prompts know exactly which surfaces the operation actually
|
|
289
|
+
* touches, and translators can author per-delivery copy when a specific
|
|
290
|
+
* channel needs different wording (e.g. SMS character limits vs WebSocket
|
|
291
|
+
* activity-feed prose).
|
|
292
|
+
*/
|
|
293
|
+
export interface ResourceOperationNotificationDeliverySpecification {
|
|
294
|
+
/**
|
|
295
|
+
* Audience description: who receives this delivery (the actor themselves
|
|
296
|
+
* via FRONT_END_SUCCESS, the rest of the organization via WEBSOCKET, …).
|
|
297
|
+
* Required — the deliveries axis exists specifically to distinguish
|
|
298
|
+
* audiences, so an undocumented audience defeats the purpose of fanning
|
|
299
|
+
* out.
|
|
300
|
+
*/
|
|
301
|
+
audience: string;
|
|
302
|
+
/**
|
|
303
|
+
* Channel the runtime fires through (e.g. `FRONT_END_SUCCESS`, `WEBSOCKET`,
|
|
304
|
+
* `SMS`, `PUSH`). Authoring sites should use `CoreUserNotificationChannel`
|
|
305
|
+
* members for built-in channels (autocomplete + typo-protection); custom
|
|
306
|
+
* channels remain expressible as raw strings.
|
|
307
|
+
*/
|
|
308
|
+
channelRef: CoreUserNotificationChannel | (string & {});
|
|
309
|
+
/**
|
|
310
|
+
* Target type from the runtime `UserNotificationDefinition.target` (see
|
|
311
|
+
* `CoreUserNotificationTarget`). Documents whether the delivery is
|
|
312
|
+
* actor-only (`USER_SELF`), org-wide (`ORGANIZATION_USERS`), a specific
|
|
313
|
+
* audience (`USERS_CUSTOM` with a selector), …
|
|
314
|
+
*/
|
|
315
|
+
targetRef: CoreUserNotificationTarget | (string & {});
|
|
316
|
+
/**
|
|
317
|
+
* Operation variant this delivery belongs to. `undefined` means the default
|
|
318
|
+
* variant. Maps to `variantKey` on the runtime variant when present.
|
|
319
|
+
*/
|
|
320
|
+
variantRef?: string;
|
|
321
|
+
/**
|
|
322
|
+
* Distinguishes deliveries when the same `(variantRef, targetRef, channelRef)`
|
|
323
|
+
* triple fires multiple notifications (rare but supported by the runtime
|
|
324
|
+
* via `customNotificationRef`).
|
|
325
|
+
*/
|
|
326
|
+
customDeliveryRef?: string;
|
|
327
|
+
/** Per-delivery overrides for translatable text slots. */
|
|
328
|
+
textSlotsOverrides?: TranslationSlotSpecificationMap;
|
|
329
|
+
/** Per-delivery override for `purpose` when this delivery has its own intent. */
|
|
330
|
+
purposeOverride?: string;
|
|
331
|
+
/** Per-delivery business constraints layered on top of the parent list. */
|
|
332
|
+
additionalBusinessConstraints?: string[];
|
|
333
|
+
/** Companion/transposer caveats specific to this delivery. */
|
|
334
|
+
notes?: string[];
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Semantic overlay for the in-app notifications fired by a resource operation.
|
|
339
|
+
*
|
|
340
|
+
* Mirrors `ResourceOperationEmailSpecification` for consistency: `purpose`
|
|
341
|
+
* and `tone` are plain authoring prose; every translatable fragment (title,
|
|
342
|
+
* body, actionLabel, …) lives in `textSlots`; `eventData` documents the
|
|
343
|
+
* payload meaning. The `deliveries` array makes the engine fan-out explicit
|
|
344
|
+
* — every runtime `userNotifications[]` entry with a non-EMAIL channel maps
|
|
345
|
+
* to one entry here so the spec is never silent about a real runtime
|
|
346
|
+
* notification surface.
|
|
347
|
+
*/
|
|
348
|
+
export interface ResourceOperationNotificationSpecification {
|
|
349
|
+
/** Why this operation fires in-app notifications (shared across deliveries). */
|
|
350
|
+
purpose: string;
|
|
351
|
+
/** Expected voice/posture for the generated copy. */
|
|
352
|
+
tone: string;
|
|
353
|
+
/** Situations where this notification must be raised alongside the operation. */
|
|
354
|
+
useWhen?: string;
|
|
355
|
+
/** Situations where this notification should not fire. */
|
|
356
|
+
avoidWhen?: string;
|
|
357
|
+
/**
|
|
358
|
+
* Translatable text slots for the notification (`title`, `body`,
|
|
359
|
+
* `actionLabel`, or any channel-specific named slot). `title` is required
|
|
360
|
+
* so every notification has a recognisable headline for translators and
|
|
361
|
+
* transposers to target. Per-delivery overrides live on each
|
|
362
|
+
* `deliveries[i].textSlotsOverrides`.
|
|
363
|
+
*/
|
|
364
|
+
textSlots: TranslationSlotSpecificationMap;
|
|
365
|
+
/**
|
|
366
|
+
* Explicit fan-out: one entry per runtime `userNotifications[]` non-EMAIL
|
|
367
|
+
* delivery. At least one entry is required when a `notification` block is
|
|
368
|
+
* authored. The validator enforces uniqueness on
|
|
369
|
+
* `(variantRef, targetRef, channelRef, customDeliveryRef)` quadruples.
|
|
370
|
+
*/
|
|
371
|
+
deliveries: ResourceOperationNotificationDeliverySpecification[];
|
|
372
|
+
/** Meaning of the event payload the notification renders with. */
|
|
373
|
+
eventData?: TranslationSlotSpecification;
|
|
374
|
+
/** Domain/compliance caveats that matter beyond the operation's own constraints. */
|
|
375
|
+
businessConstraints?: string[];
|
|
376
|
+
/** Import-oriented coding/transposition metadata. */
|
|
377
|
+
codeHandling?: ResourceOperationNotificationSpecificationCodeHandling;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/**
|
|
381
|
+
* Import-oriented metadata for the M2M (machine-to-machine) notifications
|
|
382
|
+
* fired by a resource operation.
|
|
383
|
+
*
|
|
384
|
+
* M2M notifications are webhook-style fan-outs declared on the resource
|
|
385
|
+
* operation's `m2mNotifications[]` array (see `CoreM2MNotificationChannel` —
|
|
386
|
+
* `WEBHOOK_ORGANIZATION`, `WEBHOOK_APPLICATION`, …). They never carry
|
|
387
|
+
* user-facing copy; transposers/companion prompts only need to know the
|
|
388
|
+
* channel vocabulary, the level vocabulary, and the payload schema to
|
|
389
|
+
* generate truthful integration code.
|
|
390
|
+
*/
|
|
391
|
+
export interface ResourceOperationM2MSpecificationCodeHandling {
|
|
392
|
+
/**
|
|
393
|
+
* Public enum exposing the channel vocabulary that `deliveries[i].channelRef`
|
|
394
|
+
* members come from (for example `CoreM2MNotificationChannel`). Custom
|
|
395
|
+
* channels can still be authored as raw string refs in `channelRef`, but
|
|
396
|
+
* declaring the owning enum lets transposer layers import the canonical
|
|
397
|
+
* members when generating webhook dispatch code.
|
|
398
|
+
*/
|
|
399
|
+
channelEnum?: CodeSymbolRef;
|
|
400
|
+
/**
|
|
401
|
+
* Public enum exposing the severity vocabulary that `deliveries[i].level`
|
|
402
|
+
* members come from (for example `M2MNotificationLevel`).
|
|
403
|
+
*/
|
|
404
|
+
levelEnum?: CodeSymbolRef;
|
|
405
|
+
/**
|
|
406
|
+
* Public Zod schema describing the m2m payload (often the resource main
|
|
407
|
+
* schema augmented with operation metadata, but operations are free to
|
|
408
|
+
* publish a webhook-shaped projection).
|
|
409
|
+
*/
|
|
410
|
+
payloadSchemaSymbol?: CodeSymbolRef;
|
|
411
|
+
/** Public TypeScript type symbol when the payload type is split from its Zod schema. */
|
|
412
|
+
payloadTypeSymbol?: CodeSymbolRef;
|
|
413
|
+
/** Extra supporting symbols transposer prompts may need. */
|
|
414
|
+
supportingSymbols?: CodeSymbolRef[];
|
|
415
|
+
/** Companion/transposer caveats that must survive serialization. */
|
|
416
|
+
notes?: string[];
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* Semantic overlay for ONE M2M notification delivery fired by a resource
|
|
421
|
+
* operation. Each entry in the runtime `m2mNotifications[]` array maps to
|
|
422
|
+
* one entry here so the spec stays parity-faithful with the engine fan-out.
|
|
423
|
+
*/
|
|
424
|
+
export interface ResourceOperationM2MDeliverySpecification {
|
|
425
|
+
/**
|
|
426
|
+
* Audience description: which integration consumers receive this webhook
|
|
427
|
+
* (the organization's configured webhook endpoints, the application's
|
|
428
|
+
* platform-wide endpoint, …). Required for the same fan-out reason as the
|
|
429
|
+
* email/notification delivery audiences.
|
|
430
|
+
*/
|
|
431
|
+
audience: string;
|
|
432
|
+
/**
|
|
433
|
+
* Channel ref (e.g. `CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION`).
|
|
434
|
+
* Authoring sites should use `CoreM2MNotificationChannel` members for
|
|
435
|
+
* built-in channels (autocomplete + typo-protection); custom channels
|
|
436
|
+
* remain expressible as raw strings.
|
|
437
|
+
*/
|
|
438
|
+
channelRef: CoreM2MNotificationChannel | (string & {});
|
|
439
|
+
/**
|
|
440
|
+
* Severity classification (info / success / error). Authoring sites should
|
|
441
|
+
* use `M2MNotificationLevel` members; mirrors the runtime enum.
|
|
442
|
+
*/
|
|
443
|
+
level?: M2MNotificationLevel | (string & {});
|
|
444
|
+
/**
|
|
445
|
+
* Operation variant this delivery belongs to. `undefined` means the default
|
|
446
|
+
* variant. Maps to `variantKey` on the runtime variant when present.
|
|
447
|
+
*/
|
|
448
|
+
variantRef?: string;
|
|
449
|
+
/**
|
|
450
|
+
* Distinguishes deliveries when the same `(variantRef, channelRef, level)`
|
|
451
|
+
* triple fires multiple webhooks (e.g. one operation publishing both an
|
|
452
|
+
* org webhook and a partner-specific custom channel).
|
|
453
|
+
*/
|
|
454
|
+
customDeliveryRef?: string;
|
|
455
|
+
/** Companion/transposer caveats specific to this delivery. */
|
|
456
|
+
notes?: string[];
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/**
|
|
460
|
+
* Semantic overlay for the M2M (webhook) notifications fired by a resource
|
|
461
|
+
* operation. Mirrors the email/notification overlay shape so authors get a
|
|
462
|
+
* uniform fan-out vocabulary across all three communications surfaces.
|
|
463
|
+
*
|
|
464
|
+
* The `requiredFeatures` slot is a documentation-oriented feature-gate
|
|
465
|
+
* descriptor — see {@link RequiredFeaturesSpecification}. The runtime checks
|
|
466
|
+
* the M2M dispatch gate at its delivery boundary, so this slot documents the
|
|
467
|
+
* application intent rather than acting as enforcement.
|
|
468
|
+
* The M2M validator opts in to fail-soft cross-registry resolution (see
|
|
469
|
+
* `assertOptionalRequiredFeaturesSpecification` — `crossRegistry:
|
|
470
|
+
* 'fail-soft'`) so application-defined feature refs beyond the engine
|
|
471
|
+
* baseline do not silently re-define the runtime contract.
|
|
472
|
+
*/
|
|
473
|
+
export interface ResourceOperationM2MSpecification {
|
|
474
|
+
/** Why this operation fires M2M webhooks (shared intent across deliveries). */
|
|
475
|
+
purpose: string;
|
|
476
|
+
/** Situations where the M2M dispatch must run alongside the operation. */
|
|
477
|
+
useWhen?: string;
|
|
478
|
+
/** Situations where the M2M dispatch should not fire. */
|
|
479
|
+
avoidWhen?: string;
|
|
480
|
+
/** Domain/compliance caveats (rate limits, privacy filters, retry policy …). */
|
|
481
|
+
businessConstraints?: string[];
|
|
482
|
+
/**
|
|
483
|
+
* Explicit fan-out: one entry per runtime `m2mNotifications[]` delivery.
|
|
484
|
+
* At least one entry is required when an `m2m` block is authored.
|
|
485
|
+
*/
|
|
486
|
+
deliveries: ResourceOperationM2MDeliverySpecification[];
|
|
487
|
+
/**
|
|
488
|
+
* Documentation-oriented feature-gate descriptor — see
|
|
489
|
+
* {@link RequiredFeaturesSpecification}. Optional. The authoritative
|
|
490
|
+
* runtime gate lives at the M2M dispatcher
|
|
491
|
+
* (`featureResolution.isFeatureEnabled(M2M_WEBHOOK_DELIVERY)`); declaring
|
|
492
|
+
* this slot lets companion prompts surface the same requirement without
|
|
493
|
+
* re-implementing the runtime check. Authors may add additional
|
|
494
|
+
* application-level features here (e.g. `'PARTNER_INTEGRATION'`) when
|
|
495
|
+
* the operation's webhook fan-out is gated beyond the engine baseline.
|
|
496
|
+
*/
|
|
497
|
+
requiredFeatures?: RequiredFeaturesSpecification;
|
|
498
|
+
/** Import-oriented coding/transposition metadata. */
|
|
499
|
+
codeHandling?: ResourceOperationM2MSpecificationCodeHandling;
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
/**
|
|
503
|
+
* Outbound communications fired by a resource operation.
|
|
504
|
+
*
|
|
505
|
+
* Each sub-block is optional — an operation may send only an email, only a
|
|
506
|
+
* notification, only an m2m webhook, any combination, or none. The companion
|
|
507
|
+
* will render only the authored sub-blocks. The three sub-blocks mirror the
|
|
508
|
+
* runtime fan-out surfaces:
|
|
509
|
+
* - `email` ↔ `userNotifications[].channel === EMAIL` entries
|
|
510
|
+
* - `notification` ↔ `userNotifications[].channel !== EMAIL` entries
|
|
511
|
+
* - `m2m` ↔ `m2mNotifications[]` entries
|
|
512
|
+
*
|
|
513
|
+
* Variant-level overrides are not modelled at the parent level: deliveries
|
|
514
|
+
* carry their own `variantRef`, so per-variant differences are captured
|
|
515
|
+
* inside the `deliveries` arrays of each sub-block.
|
|
516
|
+
*/
|
|
517
|
+
export interface ResourceOperationCommunicationsSpecification {
|
|
518
|
+
/** Email deliveries fired by the operation, when applicable. */
|
|
519
|
+
email?: ResourceOperationEmailSpecification;
|
|
520
|
+
/** In-app notification deliveries fired by the operation, when applicable. */
|
|
521
|
+
notification?: ResourceOperationNotificationSpecification;
|
|
522
|
+
/** M2M (webhook) deliveries fired by the operation, when applicable. */
|
|
523
|
+
m2m?: ResourceOperationM2MSpecification;
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/**
|
|
527
|
+
* Import-oriented metadata for the scheduled execution of a resource operation.
|
|
528
|
+
*
|
|
529
|
+
* Scheduled work always anchors to `(resourceIdentifier, operationIdentifier)`
|
|
530
|
+
* at runtime — either through a `ResourceOperationVariantType.CRON_JOB`
|
|
531
|
+
* variant of the operation, or through `createCustomBatchExecutionService(...)`
|
|
532
|
+
* whose `batchCronjob_Context` pins the same anchor. Transposer/companion
|
|
533
|
+
* prompts need stable import refs to the input/output schemas and to the
|
|
534
|
+
* batch-ref constant so generated code can reuse the canonical declarations
|
|
535
|
+
* instead of re-typing them.
|
|
536
|
+
*/
|
|
537
|
+
export interface ResourceOperationScheduledExecutionCodeHandling {
|
|
538
|
+
/** Public Zod schema symbol describing the scheduled-run input payload. */
|
|
539
|
+
inputSchemaSymbol?: CodeSymbolRef;
|
|
540
|
+
/** Public Zod schema symbol describing the scheduled-run output payload. */
|
|
541
|
+
outputSchemaSymbol?: CodeSymbolRef;
|
|
542
|
+
/** Public TypeScript type symbol when the input type is split from its Zod schema. */
|
|
543
|
+
inputTypeSymbol?: CodeSymbolRef;
|
|
544
|
+
/** Public TypeScript type symbol when the output type is split from its Zod schema. */
|
|
545
|
+
outputTypeSymbol?: CodeSymbolRef;
|
|
546
|
+
/**
|
|
547
|
+
* Public symbol declaring the custom-batch reference constant (for example
|
|
548
|
+
* `FILES_CLEANUP_BATCH_REF`) when the schedule runs through
|
|
549
|
+
* `createCustomBatchExecutionService(...)` rather than a
|
|
550
|
+
* `ResourceOperationVariantType.CRON_JOB` variant.
|
|
551
|
+
*/
|
|
552
|
+
customBatchRefSymbol?: CodeSymbolRef;
|
|
553
|
+
/**
|
|
554
|
+
* Public symbol declaring the factory that builds the custom batch service
|
|
555
|
+
* (for example `createFilesCleanupBatch`). Lets generated code import the
|
|
556
|
+
* constructor directly without re-reading the batch file.
|
|
557
|
+
*/
|
|
558
|
+
batchFactorySymbol?: CodeSymbolRef;
|
|
559
|
+
/** Extra supporting symbols transposer prompts may need. */
|
|
560
|
+
supportingSymbols?: CodeSymbolRef[];
|
|
561
|
+
/** Companion/transposer caveats that must survive serialization. */
|
|
562
|
+
notes?: string[];
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
/**
|
|
566
|
+
* Discriminant vocabulary for how a scheduled unit of work is anchored to a
|
|
567
|
+
* resource operation at runtime.
|
|
568
|
+
*
|
|
569
|
+
* The spec-layer vocabulary intentionally does NOT reuse
|
|
570
|
+
* `ResourceOperationVariantType` directly. Runtime variants describe how the
|
|
571
|
+
* operation itself is declared on the resource configuration, while custom
|
|
572
|
+
* batches are a separate mechanism registered through
|
|
573
|
+
* `createCustomBatchExecutionService(...)` whose `batchCronjob_Context`
|
|
574
|
+
* happens to anchor to a `(resourceIdentifier, operationIdentifier)` pair.
|
|
575
|
+
* The three spec arms below make the distinction explicit so illegal
|
|
576
|
+
* combinations (a `CRON_JOB` variant with no cron, a `BATCH_JOB` variant
|
|
577
|
+
* with a cron, a custom batch with no `customBatchRef`, …) are
|
|
578
|
+
* unrepresentable at authoring time.
|
|
579
|
+
*/
|
|
580
|
+
export enum ResourceOperationScheduledExecutionVariantType {
|
|
581
|
+
/**
|
|
582
|
+
* Operation itself declares a `ResourceOperationVariantType.CRON_JOB`
|
|
583
|
+
* variant whose `cronJobExpression` drives the schedule. The spec echoes
|
|
584
|
+
* the same cron so companion prompts can reason about cadence without
|
|
585
|
+
* reading the runtime configuration.
|
|
586
|
+
*/
|
|
587
|
+
NATIVE_CRON_JOB = 'NATIVE_CRON_JOB',
|
|
588
|
+
/**
|
|
589
|
+
* Operation itself declares a `ResourceOperationVariantType.BATCH_JOB`
|
|
590
|
+
* variant. No cron is attached — the batch variant is event-triggered
|
|
591
|
+
* (queue message, deferred work) and runs when upstream work dispatches it.
|
|
592
|
+
*/
|
|
593
|
+
NATIVE_BATCH_JOB = 'NATIVE_BATCH_JOB',
|
|
594
|
+
/**
|
|
595
|
+
* Schedule is registered through `createCustomBatchExecutionService(...)`
|
|
596
|
+
* with a `batchCronjob_Context` pinning it to this operation. The batch
|
|
597
|
+
* lives outside the operation's own variants and is addressed by a stable
|
|
598
|
+
* `customBatchRef` that the runtime registry (and the declarative
|
|
599
|
+
* `CustomBatchManifest` aggregator) both consume.
|
|
600
|
+
*/
|
|
601
|
+
CUSTOM_BATCH = 'CUSTOM_BATCH',
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
/**
|
|
605
|
+
* Fields shared by every `scheduledExecution` arm. Authoring prose
|
|
606
|
+
* (`purpose` / `outcome`) is not translatable — scheduled runs have no
|
|
607
|
+
* user-facing copy of their own, so we do not carry `textSlots` here.
|
|
608
|
+
*/
|
|
609
|
+
interface BaseResourceOperationScheduledExecutionSpecification {
|
|
610
|
+
/** Why this scheduled work runs (business intent, not mechanics). */
|
|
611
|
+
purpose: string;
|
|
612
|
+
/** Observable business result once the scheduled run finishes successfully. */
|
|
613
|
+
outcome: string;
|
|
614
|
+
/** Situations where the scheduled run is the right business path. */
|
|
615
|
+
useWhen?: string;
|
|
616
|
+
/** Situations where the scheduled run should be suppressed (maintenance windows, migrations, …). */
|
|
617
|
+
avoidWhen?: string;
|
|
618
|
+
/** Domain/compliance caveats that matter beyond the operation's own constraints. */
|
|
619
|
+
businessConstraints?: string[];
|
|
620
|
+
/** Import-oriented coding/transposition metadata. */
|
|
621
|
+
codeHandling?: ResourceOperationScheduledExecutionCodeHandling;
|
|
622
|
+
}
|
|
623
|
+
|
|
624
|
+
/**
|
|
625
|
+
* Scheduled-execution overlay for operations whose own variants declare a
|
|
626
|
+
* `ResourceOperationVariantType.CRON_JOB` with an inline cron expression.
|
|
627
|
+
* The spec echoes that cron so companion prompts see the authoritative cadence
|
|
628
|
+
* without re-reading backend code; authors must not invent a cron the runtime
|
|
629
|
+
* variant does not declare.
|
|
630
|
+
*/
|
|
631
|
+
export interface NativeCronJobScheduledExecutionSpecification
|
|
632
|
+
extends BaseResourceOperationScheduledExecutionSpecification {
|
|
633
|
+
variantType: ResourceOperationScheduledExecutionVariantType.NATIVE_CRON_JOB;
|
|
634
|
+
/** Echoed cron expression from the operation's `CRON_JOB` variant. */
|
|
635
|
+
cronExpression: string;
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
/**
|
|
639
|
+
* Scheduled-execution overlay for operations whose own variants declare a
|
|
640
|
+
* `ResourceOperationVariantType.BATCH_JOB`. Batch variants run on dispatch
|
|
641
|
+
* rather than a schedule, so no cron is attached and no custom-batch ref is
|
|
642
|
+
* involved.
|
|
643
|
+
*/
|
|
644
|
+
export interface NativeBatchJobScheduledExecutionSpecification
|
|
645
|
+
extends BaseResourceOperationScheduledExecutionSpecification {
|
|
646
|
+
variantType: ResourceOperationScheduledExecutionVariantType.NATIVE_BATCH_JOB;
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
/**
|
|
650
|
+
* Scheduled-execution overlay for work registered through
|
|
651
|
+
* `createCustomBatchExecutionService(...)` whose `batchCronjob_Context`
|
|
652
|
+
* anchors to this operation. The stable `customBatchRef` must match the
|
|
653
|
+
* `CustomBatchManifest.batchRef` exported next to the batch factory, which
|
|
654
|
+
* in turn feeds the imperative `customBatches.set(...)` registration in
|
|
655
|
+
* `start-application.backend.service.ts`.
|
|
656
|
+
*
|
|
657
|
+
* `cronExpression` echoes the custom batch's `batchCronjob_Context.cronJobExpression`
|
|
658
|
+
* when one is declared; event-triggered custom batches (for example the
|
|
659
|
+
* email `batch-send` path) omit both the cron and the `cronExpression` field.
|
|
660
|
+
*/
|
|
661
|
+
export interface CustomBatchScheduledExecutionSpecification
|
|
662
|
+
extends BaseResourceOperationScheduledExecutionSpecification {
|
|
663
|
+
variantType: ResourceOperationScheduledExecutionVariantType.CUSTOM_BATCH;
|
|
664
|
+
/** Stable ref that resolves to a `CustomBatchManifest` at module load. */
|
|
665
|
+
customBatchRef: string;
|
|
666
|
+
/**
|
|
667
|
+
* Echoed cron expression from the custom batch's `batchCronjob_Context`.
|
|
668
|
+
* Must match the manifest: present when the batch declares a cron, absent
|
|
669
|
+
* when the batch is purely event-triggered.
|
|
670
|
+
*/
|
|
671
|
+
cronExpression?: string;
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
/**
|
|
675
|
+
* Discriminated-union semantic overlay for scheduled execution of a resource
|
|
676
|
+
* operation. The discriminant is
|
|
677
|
+
* {@link ResourceOperationScheduledExecutionVariantType} and each arm enforces
|
|
678
|
+
* the fields the runtime anchor actually requires, so illegal combinations
|
|
679
|
+
* (cron without variant, batch-job with cron, custom batch without ref, …)
|
|
680
|
+
* are rejected at authoring time.
|
|
681
|
+
*
|
|
682
|
+
* Attaching the slot at the operation level mirrors the runtime invariant
|
|
683
|
+
* that every scheduled unit of work anchors to a resource operation
|
|
684
|
+
* (`ResourceOperationVariantType.CRON_JOB` / `BATCH_JOB` or a custom batch
|
|
685
|
+
* whose `batchCronjob_Context` binds it to `(resourceIdentifier,
|
|
686
|
+
* operationIdentifier)`). There is no operation-less scheduled path.
|
|
687
|
+
*
|
|
688
|
+
* Cross-registry verification of `customBatchRef` runs at module load by
|
|
689
|
+
* consulting the declarative `CustomBatchManifest` registry — see
|
|
690
|
+
* {@link registerCustomBatchManifests} and the engine's
|
|
691
|
+
* `ENGINE_CUSTOM_BATCH_MANIFESTS` export in `@wildo-ai/saas-backend-lib`.
|
|
692
|
+
*/
|
|
693
|
+
export type ResourceOperationScheduledExecutionSpecification =
|
|
694
|
+
| NativeCronJobScheduledExecutionSpecification
|
|
695
|
+
| NativeBatchJobScheduledExecutionSpecification
|
|
696
|
+
| CustomBatchScheduledExecutionSpecification;
|
|
697
|
+
|
|
698
|
+
// ── Operation HTTP-documentation overlay (Tier 3 — OpenAPI semantics) ───────
|
|
699
|
+
|
|
700
|
+
/**
|
|
701
|
+
* Fixed vocabulary of HTTP response status codes an operation may document.
|
|
702
|
+
* An enum (not a literal union) per the framework rule — a single source of
|
|
703
|
+
* truth for the renderer and the OpenAPI generator. The string VALUE is the
|
|
704
|
+
* OpenAPI `responses` key (`'200'`, `'404'`, …) so it splices in verbatim.
|
|
705
|
+
*/
|
|
706
|
+
export enum HttpResponseStatusCode {
|
|
707
|
+
OK_200 = '200',
|
|
708
|
+
CREATED_201 = '201',
|
|
709
|
+
ACCEPTED_202 = '202',
|
|
710
|
+
NO_CONTENT_204 = '204',
|
|
711
|
+
BAD_REQUEST_400 = '400',
|
|
712
|
+
UNAUTHORIZED_401 = '401',
|
|
713
|
+
FORBIDDEN_403 = '403',
|
|
714
|
+
NOT_FOUND_404 = '404',
|
|
715
|
+
CONFLICT_409 = '409',
|
|
716
|
+
UNPROCESSABLE_ENTITY_422 = '422',
|
|
717
|
+
TOO_MANY_REQUESTS_429 = '429',
|
|
718
|
+
INTERNAL_SERVER_ERROR_500 = '500',
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
/**
|
|
722
|
+
* One documented response status for an operation. Becomes an OpenAPI
|
|
723
|
+
* `responses.<code>` entry whose `description` is the authored `meaning`.
|
|
724
|
+
*/
|
|
725
|
+
export interface ResourceOperationResponseStatusSpecification {
|
|
726
|
+
/** HTTP status code this operation returns on this outcome. */
|
|
727
|
+
code: HttpResponseStatusCode;
|
|
728
|
+
/** What this status means for THIS operation, in business terms. */
|
|
729
|
+
meaning: string;
|
|
730
|
+
}
|
|
731
|
+
|
|
732
|
+
/**
|
|
733
|
+
* One documented failure mode beyond the happy path. Becomes an OpenAPI error
|
|
734
|
+
* `responses.<code>` entry; `when` explains the trigger and `errorCode` (if
|
|
735
|
+
* set) is the machine-stable identifier the API returns in the error body.
|
|
736
|
+
*/
|
|
737
|
+
export interface ResourceOperationErrorScenarioSpecification {
|
|
738
|
+
/** HTTP status code returned in this failure mode. */
|
|
739
|
+
code: HttpResponseStatusCode;
|
|
740
|
+
/** Trigger condition — when/why this error occurs. */
|
|
741
|
+
when: string;
|
|
742
|
+
/** Optional machine-stable error identifier emitted in the error body. */
|
|
743
|
+
errorCode?: string;
|
|
744
|
+
}
|
|
745
|
+
|
|
746
|
+
/**
|
|
747
|
+
* A request/response payload example for docs + client codegen. Becomes an
|
|
748
|
+
* OpenAPI example on the request body and/or the `forStatus` response.
|
|
749
|
+
*/
|
|
750
|
+
export interface ResourceOperationExampleSpecification {
|
|
751
|
+
/** Short human label, e.g. "Create with assignee". */
|
|
752
|
+
title: string;
|
|
753
|
+
/** Optional example request body (JSON-serialisable). */
|
|
754
|
+
request?: unknown;
|
|
755
|
+
/** Optional example response body (JSON-serialisable). */
|
|
756
|
+
response?: unknown;
|
|
757
|
+
/** Which response status this example illustrates (links to `responseStatuses`). */
|
|
758
|
+
forStatus?: HttpResponseStatusCode;
|
|
759
|
+
}
|
|
760
|
+
|
|
761
|
+
/**
|
|
762
|
+
* Semantic explanation for one logical resource operation.
|
|
763
|
+
*
|
|
764
|
+
* The operation-level fields capture the invariant business meaning of the
|
|
765
|
+
* action, while `variants` captures frontend/runtime-specific differences when
|
|
766
|
+
* multiple operation variants exist.
|
|
767
|
+
*/
|
|
768
|
+
export interface ResourceOperationSpecification {
|
|
769
|
+
/** Stable operation identifier as declared by the resource configuration. */
|
|
770
|
+
operationId?: string;
|
|
771
|
+
/** Shared business intent across all variants of the operation. */
|
|
772
|
+
purpose?: string;
|
|
773
|
+
/** Shared observable business result once the operation succeeds. */
|
|
774
|
+
outcome?: string;
|
|
775
|
+
/** Guidance about when this operation is the right choice. */
|
|
776
|
+
whenToUse?: string;
|
|
777
|
+
/** Relative weight of this operation in the resource understanding. */
|
|
778
|
+
importance?: FieldSemanticImportance;
|
|
779
|
+
/**
|
|
780
|
+
* Outbound communications (emails, notifications) fired as a side-effect of
|
|
781
|
+
* running the operation. Because `ResourceFrontendViewSpecification`
|
|
782
|
+
* structurally extends this interface, communications authored at the base
|
|
783
|
+
* level are automatically visible through `frontend.views` as well.
|
|
784
|
+
*/
|
|
785
|
+
communications?: ResourceOperationCommunicationsSpecification;
|
|
786
|
+
/**
|
|
787
|
+
* Scheduled-execution overlay for cron/batch operations. Applies when the
|
|
788
|
+
* operation has a `CRON_JOB` / `BATCH_JOB` variant or is implemented by a
|
|
789
|
+
* custom batch whose `batchCronjob_Context` anchors to this operation.
|
|
790
|
+
* Attached at the base level so it also surfaces through
|
|
791
|
+
* `frontend.views` via structural inheritance — scheduled work is a
|
|
792
|
+
* backend-initiated side effect, not a UI seam.
|
|
793
|
+
*/
|
|
794
|
+
scheduledExecution?: ResourceOperationScheduledExecutionSpecification;
|
|
795
|
+
/** Variant-specific semantics layered under the same logical operation id. */
|
|
796
|
+
variants?: ResourceOperationSpecificationVariants;
|
|
797
|
+
/**
|
|
798
|
+
* Authored HTTP response statuses for this operation. Feeds the OpenAPI
|
|
799
|
+
* `responses` object, replacing the generator's default single `200`/`204`.
|
|
800
|
+
* Per-operation — variants share the same HTTP contract (a per-variant
|
|
801
|
+
* response set would multiply identical contracts with no semantic gain).
|
|
802
|
+
*/
|
|
803
|
+
responseStatuses?: ResourceOperationResponseStatusSpecification[];
|
|
804
|
+
/**
|
|
805
|
+
* Failure modes a client should handle beyond the happy path. Each becomes
|
|
806
|
+
* an OpenAPI error `responses` entry (400/403/404/409/…) carrying its `when`
|
|
807
|
+
* prose. Per-operation.
|
|
808
|
+
*/
|
|
809
|
+
errorScenarios?: ResourceOperationErrorScenarioSpecification[];
|
|
810
|
+
/**
|
|
811
|
+
* Whether repeating the request with the same input is side-effect-free.
|
|
812
|
+
* Surfaces as an OpenAPI `x-idempotent` extension plus a description note.
|
|
813
|
+
*/
|
|
814
|
+
idempotent?: boolean;
|
|
815
|
+
/** Optional human note on the operation's rate-limiting posture (free prose). */
|
|
816
|
+
rateLimitNote?: string;
|
|
817
|
+
/**
|
|
818
|
+
* Request/response payload examples for docs + client codegen. Base examples
|
|
819
|
+
* apply to every variant unless `variants.<key>.examples` provides a complete
|
|
820
|
+
* replacement for a divergent variant response schema.
|
|
821
|
+
*/
|
|
822
|
+
examples?: ResourceOperationExampleSpecification[];
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
/**
|
|
826
|
+
* Validation entry point used by the resource specification factory to assert
|
|
827
|
+
* that an authored `communications` block is internally consistent. Factories
|
|
828
|
+
* call this from the same place they already assert frontend-operation
|
|
829
|
+
* completeness, so misconfigurations fail at module load rather than leaking
|
|
830
|
+
* into companion renderers as half-formed prose.
|
|
831
|
+
*
|
|
832
|
+
* @param ownerLabel Stable identifier of the owning operation (used in error
|
|
833
|
+
* messages so authors can locate the broken spec immediately).
|
|
834
|
+
* @param communications The authored communications block, or undefined when
|
|
835
|
+
* the operation does not declare one.
|
|
836
|
+
* @param resourcePrimaryScope The owning resource's `resourcePrimaryScope`.
|
|
837
|
+
* This is the specification author's explicitly declared scope (the fourth
|
|
838
|
+
* `options` argument to {@link resourceSpecification}), threaded through
|
|
839
|
+
* every re-validation path (including
|
|
840
|
+
* {@link resourceSpecificationFromFrontendConfiguration}'s
|
|
841
|
+
* `base.operations` / `base.frontend.views` / `frontend.views`
|
|
842
|
+
* re-validation passes). It MAY still be `undefined` only on hand-built
|
|
843
|
+
* spec configs that bypass both factories — those paths intentionally
|
|
844
|
+
* soft-skip the cross-check because they have no contract with the spec
|
|
845
|
+
* author for declaring scope. The primary entry point hard-fails on
|
|
846
|
+
* missing scope (TypeScript-enforced), so production specs always
|
|
847
|
+
* exercise the cross-check.
|
|
848
|
+
*/
|
|
849
|
+
export function validateResourceOperationCommunicationsSpecification(
|
|
850
|
+
ownerLabel: string,
|
|
851
|
+
communications: ResourceOperationCommunicationsSpecification | undefined,
|
|
852
|
+
resourcePrimaryScope?: ResourcePrimaryScope,
|
|
853
|
+
): void {
|
|
854
|
+
if (!communications) {
|
|
855
|
+
return;
|
|
856
|
+
}
|
|
857
|
+
if (communications.email) {
|
|
858
|
+
assertNonEmptyProseSlot(
|
|
859
|
+
ownerLabel,
|
|
860
|
+
'communications.email.purpose',
|
|
861
|
+
communications.email.purpose,
|
|
862
|
+
);
|
|
863
|
+
assertNonEmptyProseSlot(ownerLabel, 'communications.email.tone', communications.email.tone);
|
|
864
|
+
assertOptionalNonEmptyProseSlot(
|
|
865
|
+
ownerLabel,
|
|
866
|
+
'communications.email.useWhen',
|
|
867
|
+
communications.email.useWhen,
|
|
868
|
+
);
|
|
869
|
+
assertOptionalNonEmptyProseSlot(
|
|
870
|
+
ownerLabel,
|
|
871
|
+
'communications.email.avoidWhen',
|
|
872
|
+
communications.email.avoidWhen,
|
|
873
|
+
);
|
|
874
|
+
assertEveryAuthoredTextSlot(
|
|
875
|
+
ownerLabel,
|
|
876
|
+
'email',
|
|
877
|
+
['subject'],
|
|
878
|
+
communications.email.textSlots,
|
|
879
|
+
);
|
|
880
|
+
assertOptionalEventDataSlot(ownerLabel, 'email', communications.email.eventData);
|
|
881
|
+
assertOptionalNonEmptyStringList(
|
|
882
|
+
ownerLabel,
|
|
883
|
+
'communications.email.businessConstraints',
|
|
884
|
+
communications.email.businessConstraints,
|
|
885
|
+
);
|
|
886
|
+
assertOptionalNonEmptyStringList(
|
|
887
|
+
ownerLabel,
|
|
888
|
+
'communications.email.codeHandling.notes',
|
|
889
|
+
communications.email.codeHandling?.notes,
|
|
890
|
+
);
|
|
891
|
+
assertEmailDeliveries(ownerLabel, communications.email.deliveries);
|
|
892
|
+
}
|
|
893
|
+
if (communications.notification) {
|
|
894
|
+
assertNonEmptyProseSlot(
|
|
895
|
+
ownerLabel,
|
|
896
|
+
'communications.notification.purpose',
|
|
897
|
+
communications.notification.purpose,
|
|
898
|
+
);
|
|
899
|
+
assertNonEmptyProseSlot(
|
|
900
|
+
ownerLabel,
|
|
901
|
+
'communications.notification.tone',
|
|
902
|
+
communications.notification.tone,
|
|
903
|
+
);
|
|
904
|
+
assertOptionalNonEmptyProseSlot(
|
|
905
|
+
ownerLabel,
|
|
906
|
+
'communications.notification.useWhen',
|
|
907
|
+
communications.notification.useWhen,
|
|
908
|
+
);
|
|
909
|
+
assertOptionalNonEmptyProseSlot(
|
|
910
|
+
ownerLabel,
|
|
911
|
+
'communications.notification.avoidWhen',
|
|
912
|
+
communications.notification.avoidWhen,
|
|
913
|
+
);
|
|
914
|
+
assertEveryAuthoredTextSlot(
|
|
915
|
+
ownerLabel,
|
|
916
|
+
'notification',
|
|
917
|
+
['title'],
|
|
918
|
+
communications.notification.textSlots,
|
|
919
|
+
);
|
|
920
|
+
assertOptionalEventDataSlot(
|
|
921
|
+
ownerLabel,
|
|
922
|
+
'notification',
|
|
923
|
+
communications.notification.eventData,
|
|
924
|
+
);
|
|
925
|
+
assertOptionalNonEmptyStringList(
|
|
926
|
+
ownerLabel,
|
|
927
|
+
'communications.notification.businessConstraints',
|
|
928
|
+
communications.notification.businessConstraints,
|
|
929
|
+
);
|
|
930
|
+
assertOptionalNonEmptyStringList(
|
|
931
|
+
ownerLabel,
|
|
932
|
+
'communications.notification.codeHandling.notes',
|
|
933
|
+
communications.notification.codeHandling?.notes,
|
|
934
|
+
);
|
|
935
|
+
assertNotificationDeliveries(ownerLabel, communications.notification.deliveries);
|
|
936
|
+
}
|
|
937
|
+
if (communications.m2m) {
|
|
938
|
+
assertNonEmptyProseSlot(ownerLabel, 'communications.m2m.purpose', communications.m2m.purpose);
|
|
939
|
+
assertOptionalNonEmptyProseSlot(
|
|
940
|
+
ownerLabel,
|
|
941
|
+
'communications.m2m.useWhen',
|
|
942
|
+
communications.m2m.useWhen,
|
|
943
|
+
);
|
|
944
|
+
assertOptionalNonEmptyProseSlot(
|
|
945
|
+
ownerLabel,
|
|
946
|
+
'communications.m2m.avoidWhen',
|
|
947
|
+
communications.m2m.avoidWhen,
|
|
948
|
+
);
|
|
949
|
+
assertOptionalNonEmptyStringList(
|
|
950
|
+
ownerLabel,
|
|
951
|
+
'communications.m2m.businessConstraints',
|
|
952
|
+
communications.m2m.businessConstraints,
|
|
953
|
+
);
|
|
954
|
+
assertOptionalNonEmptyStringList(
|
|
955
|
+
ownerLabel,
|
|
956
|
+
'communications.m2m.codeHandling.notes',
|
|
957
|
+
communications.m2m.codeHandling?.notes,
|
|
958
|
+
);
|
|
959
|
+
assertOptionalRequiredFeaturesSpecification(
|
|
960
|
+
`Resource operation "${ownerLabel}" communications.m2m.requiredFeatures`,
|
|
961
|
+
communications.m2m.requiredFeatures,
|
|
962
|
+
{ crossRegistry: 'fail-soft' },
|
|
963
|
+
);
|
|
964
|
+
assertM2MDeliveries(ownerLabel, communications.m2m.deliveries, resourcePrimaryScope);
|
|
965
|
+
}
|
|
966
|
+
}
|
|
967
|
+
|
|
968
|
+
/**
|
|
969
|
+
* Assert that a REQUIRED prose slot (`purpose`, `tone`, `audience`, …) is
|
|
970
|
+
* non-empty trimmed. `slotLabel` is the full owner-relative path included
|
|
971
|
+
* verbatim in the error (e.g. `communications.email.purpose`,
|
|
972
|
+
* `communications.email.deliveries[0].audience`) so callers can locate the
|
|
973
|
+
* broken authoring site immediately, regardless of whether the slot lives
|
|
974
|
+
* directly under `communications.*` or further nested under a `deliveries[i]`.
|
|
975
|
+
*/
|
|
976
|
+
function assertNonEmptyProseSlot(
|
|
977
|
+
ownerLabel: string,
|
|
978
|
+
slotLabel: string,
|
|
979
|
+
value: string | undefined,
|
|
980
|
+
): void {
|
|
981
|
+
if (!value || !value.trim()) {
|
|
982
|
+
throw new Error(
|
|
983
|
+
`Resource operation "${ownerLabel}" ${slotLabel} must be a non-empty prose slot.`,
|
|
984
|
+
);
|
|
985
|
+
}
|
|
986
|
+
}
|
|
987
|
+
|
|
988
|
+
/**
|
|
989
|
+
* Best-effort resource-type hint derivation from the `_factory` argument
|
|
990
|
+
* passed to `resourceSpecification(...)`.
|
|
991
|
+
*
|
|
992
|
+
* Used exclusively to enrich the `validateFieldShapes(...)` error prefix so
|
|
993
|
+
* authors see `resourceSpecification(TODOS): ...` instead of a
|
|
994
|
+
* bare `resourceSpecification(): ...` when multiple resources fail
|
|
995
|
+
* validation in the same bundle. Returns an empty string when the hint
|
|
996
|
+
* cannot be derived — callers must treat that case as "use the bare
|
|
997
|
+
* prefix" rather than throwing.
|
|
998
|
+
*
|
|
999
|
+
* Handles both factory forms:
|
|
1000
|
+
* - Function form (`ResourceConfiguration_InitializationFactory`): reads
|
|
1001
|
+
* the function `name` and strips the standard
|
|
1002
|
+
* `_ResourceConfiguration_InitializationFactory` suffix. This matches the
|
|
1003
|
+
* application factory naming convention.
|
|
1004
|
+
* - Object form (`ResourceConfiguration`): reads the
|
|
1005
|
+
* `resourceType?.memberName` when present. Older static object-form
|
|
1006
|
+
* factories do not always set this; the empty-string fallback keeps
|
|
1007
|
+
* them working.
|
|
1008
|
+
*/
|
|
1009
|
+
function extractResourceTypeHintFromFactory(factory: unknown): string {
|
|
1010
|
+
if (typeof factory === 'function') {
|
|
1011
|
+
const name = typeof factory.name === 'string' ? factory.name : '';
|
|
1012
|
+
const stripped = name.replace(/_ResourceConfiguration_InitializationFactory$/, '');
|
|
1013
|
+
return stripped.trim();
|
|
1014
|
+
}
|
|
1015
|
+
if (factory && typeof factory === 'object') {
|
|
1016
|
+
const maybeRef = (factory as { resourceType?: { memberName?: unknown } }).resourceType;
|
|
1017
|
+
if (maybeRef && typeof maybeRef.memberName === 'string') {
|
|
1018
|
+
return maybeRef.memberName;
|
|
1019
|
+
}
|
|
1020
|
+
}
|
|
1021
|
+
return '';
|
|
1022
|
+
}
|
|
1023
|
+
|
|
1024
|
+
/**
|
|
1025
|
+
* Assert that an OPTIONAL prose slot (`useWhen`, `avoidWhen`, `purposeOverride`,
|
|
1026
|
+
* …) is non-empty trimmed when authored. Absent slots are a no-op.
|
|
1027
|
+
*
|
|
1028
|
+
* Mirrors the per-bullet contract on `assertOptionalNonEmptyStringList`: every
|
|
1029
|
+
* surface the renderer prints — even optional ones — must fail closed on
|
|
1030
|
+
* blanks because a blank `useWhen` line silently appears as `Use when .` in
|
|
1031
|
+
* companion prompts and undermines translator/transposer grounding.
|
|
1032
|
+
*
|
|
1033
|
+
* `slotLabel` is the full owner-relative path included verbatim in the error
|
|
1034
|
+
* (e.g. `email.useWhen`, `scheduledExecution.avoidWhen`,
|
|
1035
|
+
* `communications.email.deliveries[0].purposeOverride`) so callers can locate
|
|
1036
|
+
* the broken authoring site immediately.
|
|
1037
|
+
*/
|
|
1038
|
+
function assertOptionalNonEmptyProseSlot(
|
|
1039
|
+
ownerLabel: string,
|
|
1040
|
+
slotLabel: string,
|
|
1041
|
+
value: string | undefined,
|
|
1042
|
+
): void {
|
|
1043
|
+
if (value === undefined) {
|
|
1044
|
+
return;
|
|
1045
|
+
}
|
|
1046
|
+
if (typeof value !== 'string' || !value.trim()) {
|
|
1047
|
+
throw new Error(
|
|
1048
|
+
`Resource operation "${ownerLabel}" ${slotLabel} must be a non-empty trimmed prose slot when authored (omit the field entirely instead of declaring an empty value).`,
|
|
1049
|
+
);
|
|
1050
|
+
}
|
|
1051
|
+
}
|
|
1052
|
+
|
|
1053
|
+
/**
|
|
1054
|
+
* Validate the `deliveries` array on a `ResourceOperationEmailSpecification`.
|
|
1055
|
+
*
|
|
1056
|
+
* Engine-parity contract: every entry must mirror one runtime
|
|
1057
|
+
* `userNotifications[]` email delivery, so the spec is never silent about a
|
|
1058
|
+
* real runtime template path. The validator enforces:
|
|
1059
|
+
* - at least one delivery (the array is required when an `email` block is
|
|
1060
|
+
* authored — single-delivery emails still need one explicit entry),
|
|
1061
|
+
* - non-empty `audience` and `targetRef` on every delivery,
|
|
1062
|
+
* - non-empty trimmed `variantRef` / `customDeliveryRef` when authored,
|
|
1063
|
+
* - non-empty trimmed `purposeOverride` when authored,
|
|
1064
|
+
* - per-delivery `systemEmailTemplateRef` (when authored) is a member of
|
|
1065
|
+
* `SystemEmailTemplateRegistry` — the cross-link lives per-delivery
|
|
1066
|
+
* because the runtime template-ref path is per-delivery,
|
|
1067
|
+
* - per-delivery `textSlotsOverrides` slots carry a non-empty `purpose`,
|
|
1068
|
+
* - per-delivery `additionalBusinessConstraints` and `notes` follow the
|
|
1069
|
+
* per-bullet non-empty contract,
|
|
1070
|
+
* - uniqueness on `(variantRef ?? '__default__', targetRef, customDeliveryRef ?? '__none__')`
|
|
1071
|
+
* so two deliveries cannot collide on the runtime template-ref path.
|
|
1072
|
+
*/
|
|
1073
|
+
function assertEmailDeliveries(
|
|
1074
|
+
ownerLabel: string,
|
|
1075
|
+
deliveries: ResourceOperationEmailDeliverySpecification[] | undefined,
|
|
1076
|
+
): void {
|
|
1077
|
+
if (!deliveries || deliveries.length === 0) {
|
|
1078
|
+
throw new Error(
|
|
1079
|
+
`Resource operation "${ownerLabel}" communications.email.deliveries must declare at least one delivery so the spec is never silent about a real runtime email template path. Even single-delivery emails need one explicit entry.`,
|
|
1080
|
+
);
|
|
1081
|
+
}
|
|
1082
|
+
const seenKeys = new Set<string>();
|
|
1083
|
+
for (const [index, delivery] of deliveries.entries()) {
|
|
1084
|
+
const path = `communications.email.deliveries[${index}]`;
|
|
1085
|
+
assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
|
|
1086
|
+
if (typeof delivery.targetRef !== 'string' || !delivery.targetRef.trim()) {
|
|
1087
|
+
throw new Error(
|
|
1088
|
+
`Resource operation "${ownerLabel}" ${path}.targetRef must be a non-empty trimmed string (use a CoreUserNotificationTarget member or a custom target ref).`,
|
|
1089
|
+
);
|
|
1090
|
+
}
|
|
1091
|
+
assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
|
|
1092
|
+
assertOptionalNonEmptyProseSlot(
|
|
1093
|
+
ownerLabel,
|
|
1094
|
+
`${path}.customDeliveryRef`,
|
|
1095
|
+
delivery.customDeliveryRef,
|
|
1096
|
+
);
|
|
1097
|
+
assertSystemEmailTemplateCrossLink(
|
|
1098
|
+
ownerLabel,
|
|
1099
|
+
`${path}.systemEmailTemplateRef`,
|
|
1100
|
+
delivery.systemEmailTemplateRef,
|
|
1101
|
+
);
|
|
1102
|
+
assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.purposeOverride`, delivery.purposeOverride);
|
|
1103
|
+
assertTextSlotsOverrides(
|
|
1104
|
+
ownerLabel,
|
|
1105
|
+
`${path}.textSlotsOverrides`,
|
|
1106
|
+
delivery.textSlotsOverrides,
|
|
1107
|
+
);
|
|
1108
|
+
assertOptionalNonEmptyStringList(
|
|
1109
|
+
ownerLabel,
|
|
1110
|
+
`${path}.additionalBusinessConstraints`,
|
|
1111
|
+
delivery.additionalBusinessConstraints,
|
|
1112
|
+
);
|
|
1113
|
+
assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
|
|
1114
|
+
|
|
1115
|
+
const key = `${delivery.variantRef ?? '__default__'}::${delivery.targetRef}::${delivery.customDeliveryRef ?? '__none__'}`;
|
|
1116
|
+
if (seenKeys.has(key)) {
|
|
1117
|
+
throw new Error(
|
|
1118
|
+
`Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, targetRef, customDeliveryRef) triple of an earlier delivery. Two deliveries with the same triple compute the same runtime template-ref path and would silently shadow each other; add a distinguishing customDeliveryRef or merge the entries.`,
|
|
1119
|
+
);
|
|
1120
|
+
}
|
|
1121
|
+
seenKeys.add(key);
|
|
1122
|
+
}
|
|
1123
|
+
}
|
|
1124
|
+
|
|
1125
|
+
/**
|
|
1126
|
+
* Validate the `deliveries` array on a `ResourceOperationNotificationSpecification`.
|
|
1127
|
+
* Same engine-parity contract as {@link assertEmailDeliveries}, with `channelRef`
|
|
1128
|
+
* added to the uniqueness key (notifications fan out per (target, channel) pair).
|
|
1129
|
+
*/
|
|
1130
|
+
function assertNotificationDeliveries(
|
|
1131
|
+
ownerLabel: string,
|
|
1132
|
+
deliveries: ResourceOperationNotificationDeliverySpecification[] | undefined,
|
|
1133
|
+
): void {
|
|
1134
|
+
if (!deliveries || deliveries.length === 0) {
|
|
1135
|
+
throw new Error(
|
|
1136
|
+
`Resource operation "${ownerLabel}" communications.notification.deliveries must declare at least one delivery so companion routing cannot invent an in-app surface that the runtime does not fire.`,
|
|
1137
|
+
);
|
|
1138
|
+
}
|
|
1139
|
+
const seenKeys = new Set<string>();
|
|
1140
|
+
for (const [index, delivery] of deliveries.entries()) {
|
|
1141
|
+
const path = `communications.notification.deliveries[${index}]`;
|
|
1142
|
+
assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
|
|
1143
|
+
if (typeof delivery.channelRef !== 'string' || !delivery.channelRef.trim()) {
|
|
1144
|
+
throw new Error(
|
|
1145
|
+
`Resource operation "${ownerLabel}" ${path}.channelRef must be a non-empty trimmed string (use a CoreUserNotificationChannel member or a custom channel ref).`,
|
|
1146
|
+
);
|
|
1147
|
+
}
|
|
1148
|
+
if (typeof delivery.targetRef !== 'string' || !delivery.targetRef.trim()) {
|
|
1149
|
+
throw new Error(
|
|
1150
|
+
`Resource operation "${ownerLabel}" ${path}.targetRef must be a non-empty trimmed string (use a CoreUserNotificationTarget member or a custom target ref).`,
|
|
1151
|
+
);
|
|
1152
|
+
}
|
|
1153
|
+
assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
|
|
1154
|
+
assertOptionalNonEmptyProseSlot(
|
|
1155
|
+
ownerLabel,
|
|
1156
|
+
`${path}.customDeliveryRef`,
|
|
1157
|
+
delivery.customDeliveryRef,
|
|
1158
|
+
);
|
|
1159
|
+
assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.purposeOverride`, delivery.purposeOverride);
|
|
1160
|
+
assertTextSlotsOverrides(
|
|
1161
|
+
ownerLabel,
|
|
1162
|
+
`${path}.textSlotsOverrides`,
|
|
1163
|
+
delivery.textSlotsOverrides,
|
|
1164
|
+
);
|
|
1165
|
+
assertOptionalNonEmptyStringList(
|
|
1166
|
+
ownerLabel,
|
|
1167
|
+
`${path}.additionalBusinessConstraints`,
|
|
1168
|
+
delivery.additionalBusinessConstraints,
|
|
1169
|
+
);
|
|
1170
|
+
assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
|
|
1171
|
+
|
|
1172
|
+
const key = `${delivery.variantRef ?? '__default__'}::${delivery.targetRef}::${delivery.channelRef}::${delivery.customDeliveryRef ?? '__none__'}`;
|
|
1173
|
+
if (seenKeys.has(key)) {
|
|
1174
|
+
throw new Error(
|
|
1175
|
+
`Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, targetRef, channelRef, customDeliveryRef) quadruple of an earlier delivery; add a distinguishing customDeliveryRef or merge the entries.`,
|
|
1176
|
+
);
|
|
1177
|
+
}
|
|
1178
|
+
seenKeys.add(key);
|
|
1179
|
+
}
|
|
1180
|
+
}
|
|
1181
|
+
|
|
1182
|
+
/**
|
|
1183
|
+
* Validate the `deliveries` array on a `ResourceOperationM2MSpecification`.
|
|
1184
|
+
*
|
|
1185
|
+
* Webhook-style M2M deliveries fan out per
|
|
1186
|
+
* `(variantRef, channelRef, level, customDeliveryRef)` — the validator
|
|
1187
|
+
* enforces uniqueness on that quadruple so two deliveries that genuinely
|
|
1188
|
+
* differ on those axes can coexist. `variantRef` is the first segment of
|
|
1189
|
+
* the key (defaulting to `__default__` when omitted), so two deliveries
|
|
1190
|
+
* that differ only by their owning variant remain distinct.
|
|
1191
|
+
*
|
|
1192
|
+
* Each authored `level` (when present) is also enum-membership-checked
|
|
1193
|
+
* against `M2MNotificationLevel` so a typo (`'inf0'`, `'WARN'`,
|
|
1194
|
+
* …) fails at module load — the runtime schema is strict-enum even
|
|
1195
|
+
* though the TypeScript declaration is widened with `(string & {})` for
|
|
1196
|
+
* IDE autocomplete.
|
|
1197
|
+
*
|
|
1198
|
+
* **Runtime-identity cross-check.** The runtime
|
|
1199
|
+
* `M2MNotificationDefinitionSchema` carries no `customNotificationRef`
|
|
1200
|
+
* field; the dispatcher constructs the fan-out identifier as
|
|
1201
|
+
* `${resourceIdentifier}_${operationIdentifier}_${channel}` only — no
|
|
1202
|
+
* variant, no level and no custom-reference segment.
|
|
1203
|
+
* The spec layer is therefore free to author multiple deliveries on the
|
|
1204
|
+
* same `channelRef` (disambiguated by `level` / `customDeliveryRef`), but
|
|
1205
|
+
* at runtime they would collapse to a single identifier and one of the
|
|
1206
|
+
* deliveries would silently shadow the other. The validator fail-closes
|
|
1207
|
+
* on this collision: every authored delivery must project to a unique
|
|
1208
|
+
* `channelRef` within its operation. Authors who genuinely need multiple
|
|
1209
|
+
* fan-outs on the same channel must wait until the runtime carries a
|
|
1210
|
+
* `customNotificationRef` axis (engineering scope, separate workstream).
|
|
1211
|
+
*/
|
|
1212
|
+
function assertM2MDeliveries(
|
|
1213
|
+
ownerLabel: string,
|
|
1214
|
+
deliveries: ResourceOperationM2MDeliverySpecification[] | undefined,
|
|
1215
|
+
resourcePrimaryScope?: ResourcePrimaryScope,
|
|
1216
|
+
): void {
|
|
1217
|
+
if (!deliveries || deliveries.length === 0) {
|
|
1218
|
+
throw new Error(
|
|
1219
|
+
`Resource operation "${ownerLabel}" communications.m2m.deliveries must declare at least one delivery so companion routing cannot invent a webhook surface that the runtime does not fire.`,
|
|
1220
|
+
);
|
|
1221
|
+
}
|
|
1222
|
+
const seenKeys = new Set<string>();
|
|
1223
|
+
const seenRuntimeIdentities = new Map<string, number>();
|
|
1224
|
+
for (const [index, delivery] of deliveries.entries()) {
|
|
1225
|
+
const path = `communications.m2m.deliveries[${index}]`;
|
|
1226
|
+
assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
|
|
1227
|
+
if (typeof delivery.channelRef !== 'string' || !delivery.channelRef.trim()) {
|
|
1228
|
+
throw new Error(
|
|
1229
|
+
`Resource operation "${ownerLabel}" ${path}.channelRef must be a non-empty trimmed string (use a CoreM2MNotificationChannel member or a custom channel ref).`,
|
|
1230
|
+
);
|
|
1231
|
+
}
|
|
1232
|
+
assertM2MChannelMatchesPrimaryScope(
|
|
1233
|
+
ownerLabel,
|
|
1234
|
+
`${path}.channelRef`,
|
|
1235
|
+
delivery.channelRef,
|
|
1236
|
+
resourcePrimaryScope,
|
|
1237
|
+
);
|
|
1238
|
+
assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.level`, delivery.level);
|
|
1239
|
+
assertOptionalM2MNotificationLevelMembership(
|
|
1240
|
+
ownerLabel,
|
|
1241
|
+
`${path}.level`,
|
|
1242
|
+
delivery.level,
|
|
1243
|
+
);
|
|
1244
|
+
assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
|
|
1245
|
+
assertOptionalNonEmptyProseSlot(
|
|
1246
|
+
ownerLabel,
|
|
1247
|
+
`${path}.customDeliveryRef`,
|
|
1248
|
+
delivery.customDeliveryRef,
|
|
1249
|
+
);
|
|
1250
|
+
assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
|
|
1251
|
+
|
|
1252
|
+
const key = `${delivery.variantRef ?? '__default__'}::${delivery.channelRef}::${delivery.level ?? '__none__'}::${delivery.customDeliveryRef ?? '__none__'}`;
|
|
1253
|
+
if (seenKeys.has(key)) {
|
|
1254
|
+
throw new Error(
|
|
1255
|
+
`Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, channelRef, level, customDeliveryRef) quadruple of an earlier delivery; add a distinguishing customDeliveryRef or merge the entries.`,
|
|
1256
|
+
);
|
|
1257
|
+
}
|
|
1258
|
+
seenKeys.add(key);
|
|
1259
|
+
|
|
1260
|
+
const runtimeIdentityKey = delivery.channelRef;
|
|
1261
|
+
const previousIndex = seenRuntimeIdentities.get(runtimeIdentityKey);
|
|
1262
|
+
if (previousIndex !== undefined) {
|
|
1263
|
+
throw new Error(
|
|
1264
|
+
`Resource operation "${ownerLabel}" ${path} collides with deliveries[${previousIndex}] on the runtime m2m identifier (resource_op_channel) — both project to channel "${runtimeIdentityKey}". The runtime M2MNotificationDefinitionSchema carries no customNotificationRef axis, so two deliveries that differ only by (variantRef, level, customDeliveryRef) collapse to a single identifier and one would silently shadow the other. Either merge the entries or wait until the runtime carries a customNotificationRef axis.`,
|
|
1265
|
+
);
|
|
1266
|
+
}
|
|
1267
|
+
seenRuntimeIdentities.set(runtimeIdentityKey, index);
|
|
1268
|
+
}
|
|
1269
|
+
}
|
|
1270
|
+
|
|
1271
|
+
/**
|
|
1272
|
+
* Iterate every authored text slot and assert it has a non-empty trimmed
|
|
1273
|
+
* `purpose`, then assert the required slot keys (`subject` for email, `title`
|
|
1274
|
+
* for notification) are also present. This protects optional translatable
|
|
1275
|
+
* fragments (`previewText`, `ctaLabel`, `body`, `actionLabel`, …) from being
|
|
1276
|
+
* authored as placeholders that the translator cannot ground in author intent.
|
|
1277
|
+
*/
|
|
1278
|
+
function assertEveryAuthoredTextSlot(
|
|
1279
|
+
ownerLabel: string,
|
|
1280
|
+
blockLabel: 'email' | 'notification',
|
|
1281
|
+
requiredSlotKeys: readonly string[],
|
|
1282
|
+
textSlots: TranslationSlotSpecificationMap | undefined,
|
|
1283
|
+
): void {
|
|
1284
|
+
for (const requiredKey of requiredSlotKeys) {
|
|
1285
|
+
const slot = textSlots?.[requiredKey];
|
|
1286
|
+
if (!slot || !slot.purpose || !slot.purpose.trim()) {
|
|
1287
|
+
throw new Error(
|
|
1288
|
+
`Resource operation "${ownerLabel}" communications.${blockLabel} must document text slot "${requiredKey}" with a non-empty purpose so translators have a grounded target.`,
|
|
1289
|
+
);
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
if (!textSlots) {
|
|
1293
|
+
return;
|
|
1294
|
+
}
|
|
1295
|
+
for (const [slotKey, slot] of Object.entries(textSlots)) {
|
|
1296
|
+
if (!slot || !slot.purpose || !slot.purpose.trim()) {
|
|
1297
|
+
throw new Error(
|
|
1298
|
+
`Resource operation "${ownerLabel}" communications.${blockLabel}.textSlots["${slotKey}"] must carry a non-empty purpose so translators have a grounded target for every authored slot.`,
|
|
1299
|
+
);
|
|
1300
|
+
}
|
|
1301
|
+
assertOptionalNonEmptyProseSlot(
|
|
1302
|
+
ownerLabel,
|
|
1303
|
+
`communications.${blockLabel}.textSlots["${slotKey}"].whenToUse`,
|
|
1304
|
+
slot.whenToUse,
|
|
1305
|
+
);
|
|
1306
|
+
assertOptionalNonEmptyStringList(
|
|
1307
|
+
ownerLabel,
|
|
1308
|
+
`communications.${blockLabel}.textSlots["${slotKey}"].notes`,
|
|
1309
|
+
slot.notes,
|
|
1310
|
+
);
|
|
1311
|
+
}
|
|
1312
|
+
}
|
|
1313
|
+
|
|
1314
|
+
/**
|
|
1315
|
+
* When `eventData` is authored on either communications sub-block, assert its
|
|
1316
|
+
* `purpose` is a non-empty trimmed string. Companion prompts use this slot to
|
|
1317
|
+
* narrate which runtime values land in each translatable text slot, so a blank
|
|
1318
|
+
* `purpose` would produce a labelled but undocumented payload reference.
|
|
1319
|
+
*/
|
|
1320
|
+
function assertOptionalEventDataSlot(
|
|
1321
|
+
ownerLabel: string,
|
|
1322
|
+
blockLabel: 'email' | 'notification',
|
|
1323
|
+
eventData: TranslationSlotSpecification | undefined,
|
|
1324
|
+
): void {
|
|
1325
|
+
if (!eventData) {
|
|
1326
|
+
return;
|
|
1327
|
+
}
|
|
1328
|
+
if (!eventData.purpose || !eventData.purpose.trim()) {
|
|
1329
|
+
throw new Error(
|
|
1330
|
+
`Resource operation "${ownerLabel}" communications.${blockLabel}.eventData must carry a non-empty purpose so companion prompts can narrate which runtime values land in each text slot.`,
|
|
1331
|
+
);
|
|
1332
|
+
}
|
|
1333
|
+
assertOptionalNonEmptyProseSlot(
|
|
1334
|
+
ownerLabel,
|
|
1335
|
+
`communications.${blockLabel}.eventData.whenToUse`,
|
|
1336
|
+
eventData.whenToUse,
|
|
1337
|
+
);
|
|
1338
|
+
assertOptionalNonEmptyStringList(
|
|
1339
|
+
ownerLabel,
|
|
1340
|
+
`communications.${blockLabel}.eventData.notes`,
|
|
1341
|
+
eventData.notes,
|
|
1342
|
+
);
|
|
1343
|
+
}
|
|
1344
|
+
|
|
1345
|
+
/**
|
|
1346
|
+
* Validate a per-delivery `textSlotsOverrides` map (or any structurally
|
|
1347
|
+
* compatible `TranslationSlotSpecificationMap`):
|
|
1348
|
+
*
|
|
1349
|
+
* - absent map → no-op,
|
|
1350
|
+
* - every authored slot must carry a non-empty trimmed `purpose`,
|
|
1351
|
+
* - every authored optional `whenToUse` (if present) must be non-empty
|
|
1352
|
+
* trimmed prose so the renderer never prints `When to use .`,
|
|
1353
|
+
* - every authored `notes` array must follow the per-bullet contract.
|
|
1354
|
+
*
|
|
1355
|
+
* Path-agnostic: callers pass the full owner-relative path prefix (for
|
|
1356
|
+
* example `communications.email.deliveries[0].textSlotsOverrides`) so this
|
|
1357
|
+
* primitive serves every overlay surface without baking a sub-tree prefix
|
|
1358
|
+
* into the helper.
|
|
1359
|
+
*/
|
|
1360
|
+
function assertTextSlotsOverrides(
|
|
1361
|
+
ownerLabel: string,
|
|
1362
|
+
pathPrefix: string,
|
|
1363
|
+
slots: TranslationSlotSpecificationMap | undefined,
|
|
1364
|
+
): void {
|
|
1365
|
+
if (!slots) {
|
|
1366
|
+
return;
|
|
1367
|
+
}
|
|
1368
|
+
for (const [slotKey, slot] of Object.entries(slots)) {
|
|
1369
|
+
if (!slot || !slot.purpose || !slot.purpose.trim()) {
|
|
1370
|
+
throw new Error(
|
|
1371
|
+
`Resource operation "${ownerLabel}" ${pathPrefix}["${slotKey}"] must carry a non-empty purpose so translators have a grounded target for every authored override.`,
|
|
1372
|
+
);
|
|
1373
|
+
}
|
|
1374
|
+
assertOptionalNonEmptyProseSlot(
|
|
1375
|
+
ownerLabel,
|
|
1376
|
+
`${pathPrefix}["${slotKey}"].whenToUse`,
|
|
1377
|
+
slot.whenToUse,
|
|
1378
|
+
);
|
|
1379
|
+
assertOptionalNonEmptyStringList(
|
|
1380
|
+
ownerLabel,
|
|
1381
|
+
`${pathPrefix}["${slotKey}"].notes`,
|
|
1382
|
+
slot.notes,
|
|
1383
|
+
);
|
|
1384
|
+
}
|
|
1385
|
+
}
|
|
1386
|
+
|
|
1387
|
+
/**
|
|
1388
|
+
* Defensive guard for any optional `string[]` companion-bullet surface
|
|
1389
|
+
* (notes arrays, businessConstraints arrays, …). When the array is absent
|
|
1390
|
+
* the check is a no-op; when present, every entry must be a non-empty
|
|
1391
|
+
* trimmed string because the renderer emits each entry as a bullet — empty
|
|
1392
|
+
* entries leak blank lines into companion prompts and break the fail-closed
|
|
1393
|
+
* contract the surrounding validators promise.
|
|
1394
|
+
*
|
|
1395
|
+
* The helper is path-agnostic: callers pass the full owner-relative path
|
|
1396
|
+
* (for example `communications.email.codeHandling.notes` or
|
|
1397
|
+
* `scheduledExecution.codeHandling.notes`) so the same primitive serves
|
|
1398
|
+
* every overlay surface without baking a sub-tree prefix into the helper.
|
|
1399
|
+
*
|
|
1400
|
+
* @param ownerLabel Stable identifier of the owning operation (used in error
|
|
1401
|
+
* messages so authors can locate the broken spec immediately).
|
|
1402
|
+
* @param fullPath Dotted owner-relative authoring path; included verbatim in
|
|
1403
|
+
* the error message.
|
|
1404
|
+
*/
|
|
1405
|
+
function assertOptionalNonEmptyStringList(
|
|
1406
|
+
ownerLabel: string,
|
|
1407
|
+
fullPath: string,
|
|
1408
|
+
values: string[] | undefined,
|
|
1409
|
+
): void {
|
|
1410
|
+
if (!values) {
|
|
1411
|
+
return;
|
|
1412
|
+
}
|
|
1413
|
+
for (const [index, value] of values.entries()) {
|
|
1414
|
+
if (typeof value !== 'string' || !value.trim()) {
|
|
1415
|
+
throw new Error(
|
|
1416
|
+
`Resource operation "${ownerLabel}" ${fullPath}[${index}] must be a non-empty trimmed string.`,
|
|
1417
|
+
);
|
|
1418
|
+
}
|
|
1419
|
+
}
|
|
1420
|
+
}
|
|
1421
|
+
|
|
1422
|
+
/**
|
|
1423
|
+
* Cross-validate the optional m2m delivery `level` against the runtime
|
|
1424
|
+
* `M2MNotificationLevel` enum so a typo (`'inf0'`, `'WARN'`, `'crit'`, …)
|
|
1425
|
+
* fails at module load instead of leaking through the spec validator and
|
|
1426
|
+
* surfacing later as a runtime Zod parse error (or, worse, leaking into
|
|
1427
|
+
* companion prompts unchanged).
|
|
1428
|
+
*
|
|
1429
|
+
* The TypeScript declaration `M2MNotificationLevel | (string & {})` exists
|
|
1430
|
+
* to give autocomplete on enum members in IDEs, but the runtime
|
|
1431
|
+
* `M2MNotificationDefinitionSchema` declares `level` as
|
|
1432
|
+
* `z.enum(M2MNotificationLevel).optional()` — strict enum-only. The spec
|
|
1433
|
+
* layer mirrors that runtime contract here so spec → runtime parity is
|
|
1434
|
+
* fail-closed at module load.
|
|
1435
|
+
*
|
|
1436
|
+
* Mirrors `assertSystemEmailTemplateCrossLink` in error-message structure:
|
|
1437
|
+
* `slotPath` is the full owner-relative path included verbatim so authors
|
|
1438
|
+
* can locate the broken delivery directly.
|
|
1439
|
+
*/
|
|
1440
|
+
function assertOptionalM2MNotificationLevelMembership(
|
|
1441
|
+
ownerLabel: string,
|
|
1442
|
+
slotPath: string,
|
|
1443
|
+
level: M2MNotificationLevel | (string & {}) | undefined,
|
|
1444
|
+
): void {
|
|
1445
|
+
if (level === undefined) {
|
|
1446
|
+
return;
|
|
1447
|
+
}
|
|
1448
|
+
const allowedValues = Object.values(M2MNotificationLevel) as string[];
|
|
1449
|
+
if (!allowedValues.includes(level)) {
|
|
1450
|
+
throw new Error(
|
|
1451
|
+
`Resource operation "${ownerLabel}" ${slotPath} "${level}" is not a member of M2MNotificationLevel (expected one of: ${allowedValues.join(', ')}). Use a M2MNotificationLevel enum value so spec → runtime parity stays fail-closed at module load.`,
|
|
1452
|
+
);
|
|
1453
|
+
}
|
|
1454
|
+
}
|
|
1455
|
+
|
|
1456
|
+
/**
|
|
1457
|
+
* Cross-validate one M2M delivery `channelRef` against the owning resource's
|
|
1458
|
+
* `resourcePrimaryScope`.
|
|
1459
|
+
*
|
|
1460
|
+
* The runtime `WEBHOOK_ORGANIZATION` channel only fires when the operation's
|
|
1461
|
+
* resource lives under an organization scope — the dispatcher resolves the
|
|
1462
|
+
* scope from the organization initiator identity, which is only present on
|
|
1463
|
+
* organization-scoped operations.
|
|
1464
|
+
* Authoring `WEBHOOK_ORGANIZATION` on an APPLICATION/USER_SELF/ANONYMOUS
|
|
1465
|
+
* resource silently no-ops at runtime and is therefore a fail-closed
|
|
1466
|
+
* authoring error here.
|
|
1467
|
+
*
|
|
1468
|
+
* `WEBHOOK_APPLICATION` is allowed on any scope: the dispatcher resolves the
|
|
1469
|
+
* application scope from the always-present
|
|
1470
|
+
* `appConfigService.applicationId`, so the channel fires regardless of the
|
|
1471
|
+
* resource's own scope. The check is therefore one-sided — only the
|
|
1472
|
+
* `WEBHOOK_ORGANIZATION` arm fails closed.
|
|
1473
|
+
*
|
|
1474
|
+
* Custom channel refs (anything other than the two `CoreM2MNotificationChannel`
|
|
1475
|
+
* members) bypass the cross-check — third-party channels declare their own
|
|
1476
|
+
* scope semantics and are not the engine's contract.
|
|
1477
|
+
*
|
|
1478
|
+
* The cross-check is skipped when `resourcePrimaryScope` is `undefined`
|
|
1479
|
+
* — a defensive guard for re-validation seams that may be reached without
|
|
1480
|
+
* a scope (e.g., test fixtures invoking the validator directly, or future
|
|
1481
|
+
* call sites that haven't been updated). All production entry points
|
|
1482
|
+
* (`resourceSpecification`, `resourceSpecificationFromFrontendConfiguration`)
|
|
1483
|
+
* thread the scope explicitly, so this branch should not fire from the main
|
|
1484
|
+
* application path.
|
|
1485
|
+
*/
|
|
1486
|
+
function assertM2MChannelMatchesPrimaryScope(
|
|
1487
|
+
ownerLabel: string,
|
|
1488
|
+
slotPath: string,
|
|
1489
|
+
channelRef: CoreM2MNotificationChannel | (string & {}),
|
|
1490
|
+
resourcePrimaryScope: ResourcePrimaryScope | undefined,
|
|
1491
|
+
): void {
|
|
1492
|
+
if (resourcePrimaryScope === undefined) {
|
|
1493
|
+
return;
|
|
1494
|
+
}
|
|
1495
|
+
if (channelRef === CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION) {
|
|
1496
|
+
if (resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) {
|
|
1497
|
+
throw new Error(
|
|
1498
|
+
`Resource operation "${ownerLabel}" ${slotPath} declares CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION on a resource whose resourcePrimaryScope is "${resourcePrimaryScope}". WEBHOOK_ORGANIZATION resolves its scope from executionContext.initiatorIds.organizationId, which is only present on resources whose resourcePrimaryScope is "${ResourcePrimaryScope.ORGANIZATIONS}" — for application/user/anonymous-scoped resources use CoreM2MNotificationChannel.WEBHOOK_APPLICATION instead so the dispatcher can resolve the scope from appConfigService.applicationId.`,
|
|
1499
|
+
);
|
|
1500
|
+
}
|
|
1501
|
+
}
|
|
1502
|
+
// WEBHOOK_APPLICATION resolves scope from appConfigService.applicationId,
|
|
1503
|
+
// which is always present, so it is allowed on every primary scope.
|
|
1504
|
+
// Custom (non-Core) channel refs intentionally bypass the cross-check —
|
|
1505
|
+
// third-party channels declare their own scope semantics.
|
|
1506
|
+
}
|
|
1507
|
+
|
|
1508
|
+
/**
|
|
1509
|
+
* Cross-validate the optional `systemEmailTemplateRef` (now per-delivery)
|
|
1510
|
+
* against the runtime `SystemEmailTemplateRegistry` so a typo or stale ref
|
|
1511
|
+
* fails at module load instead of leaking a dangling cross-link into
|
|
1512
|
+
* companion prompts. Mirrors the registered-manifest cross-validation used
|
|
1513
|
+
* by the scheduledExecution `customBatchRef` arm — same anti-pattern, same
|
|
1514
|
+
* fail-closed treatment.
|
|
1515
|
+
*
|
|
1516
|
+
* `slotPath` is the full owner-relative path (e.g.
|
|
1517
|
+
* `communications.email.deliveries[2].systemEmailTemplateRef`) so error
|
|
1518
|
+
* messages locate the broken delivery directly.
|
|
1519
|
+
*/
|
|
1520
|
+
function assertSystemEmailTemplateCrossLink(
|
|
1521
|
+
ownerLabel: string,
|
|
1522
|
+
slotPath: string,
|
|
1523
|
+
systemEmailTemplateRef: SystemEmailTemplateRef | undefined,
|
|
1524
|
+
): void {
|
|
1525
|
+
if (systemEmailTemplateRef === undefined) {
|
|
1526
|
+
return;
|
|
1527
|
+
}
|
|
1528
|
+
if (typeof systemEmailTemplateRef !== 'string' || !systemEmailTemplateRef.trim()) {
|
|
1529
|
+
throw new Error(
|
|
1530
|
+
`Resource operation "${ownerLabel}" ${slotPath} must be a non-empty trimmed SystemEmailTemplateRef value.`,
|
|
1531
|
+
);
|
|
1532
|
+
}
|
|
1533
|
+
if (!Object.prototype.hasOwnProperty.call(SystemEmailTemplateRegistry, systemEmailTemplateRef)) {
|
|
1534
|
+
throw new Error(
|
|
1535
|
+
`Resource operation "${ownerLabel}" ${slotPath} "${systemEmailTemplateRef}" is not a member of SystemEmailTemplateRegistry. Use a SystemEmailTemplateRef enum value or register the template before this spec loads.`,
|
|
1536
|
+
);
|
|
1537
|
+
}
|
|
1538
|
+
}
|
|
1539
|
+
|
|
1540
|
+
/**
|
|
1541
|
+
* Iterate an operation map and validate every authored `communications` block.
|
|
1542
|
+
*
|
|
1543
|
+
* `ownerLabelPrefix` lets factories disambiguate which seam produced the error
|
|
1544
|
+
* (base-operation vs frontend-view), since `ResourceFrontendViewSpecification`
|
|
1545
|
+
* structurally extends `ResourceOperationSpecification` and can therefore
|
|
1546
|
+
* author communications too.
|
|
1547
|
+
*/
|
|
1548
|
+
function validateResourceOperationsCommunications(
|
|
1549
|
+
ownerLabelPrefix: string,
|
|
1550
|
+
operations:
|
|
1551
|
+
| Record<string, ResourceOperationSpecification | ResourceFrontendViewSpecification | undefined>
|
|
1552
|
+
| undefined,
|
|
1553
|
+
resourcePrimaryScope?: ResourcePrimaryScope,
|
|
1554
|
+
): void {
|
|
1555
|
+
if (!operations) {
|
|
1556
|
+
return;
|
|
1557
|
+
}
|
|
1558
|
+
for (const [operationId, operationSpec] of Object.entries(operations)) {
|
|
1559
|
+
if (!operationSpec) {
|
|
1560
|
+
continue;
|
|
1561
|
+
}
|
|
1562
|
+
validateResourceOperationCommunicationsSpecification(
|
|
1563
|
+
`${ownerLabelPrefix}${operationId}`,
|
|
1564
|
+
operationSpec.communications,
|
|
1565
|
+
resourcePrimaryScope,
|
|
1566
|
+
);
|
|
1567
|
+
}
|
|
1568
|
+
}
|
|
1569
|
+
|
|
1570
|
+
const registeredCustomBatchManifests = new Map<string, CustomBatchManifest>();
|
|
1571
|
+
|
|
1572
|
+
/**
|
|
1573
|
+
* Register custom-batch manifests with the spec-layer registry so authored
|
|
1574
|
+
* `scheduledExecution.customBatchRef` values can be cross-validated at
|
|
1575
|
+
* module load. Safe to call multiple times; re-registering the same
|
|
1576
|
+
* `batchRef` with an identical manifest is a no-op, but re-registering with
|
|
1577
|
+
* a divergent shape is a fail-closed error so silent drift between the
|
|
1578
|
+
* runtime batch and the spec layer is caught immediately.
|
|
1579
|
+
*
|
|
1580
|
+
* The framework registers its built-in batches when the public specification
|
|
1581
|
+
* package is loaded. Applications with custom batches should register them
|
|
1582
|
+
* from their specification bootstrap before evaluating a resource
|
|
1583
|
+
* specification that refers to them.
|
|
1584
|
+
*
|
|
1585
|
+
* **Import-order contract — read this if you author CUSTOM_BATCH specs.**
|
|
1586
|
+
* Registering built-in batches depends on loading the public package entry.
|
|
1587
|
+
* A consumer that reaches a low-level internal module first can evaluate a
|
|
1588
|
+
* CUSTOM_BATCH-bearing resource spec against an empty registry and fail closed
|
|
1589
|
+
* on the cross-link check at
|
|
1590
|
+
* {@link validateResourceOperationScheduledExecutionSpecification}. The
|
|
1591
|
+
* fix in that case is to either (a) ensure the engine barrel is imported
|
|
1592
|
+
* first (typically via `import '@wildo-ai/saas-specifications'`), or (b)
|
|
1593
|
+
* explicitly register the manifests required by that application's bootstrap.
|
|
1594
|
+
* Both paths make the contract explicit rather than leaving availability to
|
|
1595
|
+
* import order. Test suites that reset the registry must re-seed for the same
|
|
1596
|
+
* reason.
|
|
1597
|
+
*/
|
|
1598
|
+
export function registerCustomBatchManifests(
|
|
1599
|
+
manifests: Iterable<CustomBatchManifest>,
|
|
1600
|
+
): void {
|
|
1601
|
+
for (const manifest of manifests) {
|
|
1602
|
+
if (!manifest.batchRef || !manifest.batchRef.trim()) {
|
|
1603
|
+
throw new Error('registerCustomBatchManifests(): every manifest must carry a non-empty `batchRef`.');
|
|
1604
|
+
}
|
|
1605
|
+
if (!manifest.operationIdentifier || !manifest.operationIdentifier.trim()) {
|
|
1606
|
+
throw new Error(
|
|
1607
|
+
`registerCustomBatchManifests(): manifest for "${manifest.batchRef}" must declare a non-empty trimmed \`operationIdentifier\`.`,
|
|
1608
|
+
);
|
|
1609
|
+
}
|
|
1610
|
+
assertCustomBatchManifestKindArm(manifest);
|
|
1611
|
+
const existing = registeredCustomBatchManifests.get(manifest.batchRef);
|
|
1612
|
+
if (existing && !areCustomBatchManifestsEqual(existing, manifest)) {
|
|
1613
|
+
throw new Error(
|
|
1614
|
+
`registerCustomBatchManifests(): manifest for "${manifest.batchRef}" was registered twice with divergent shapes. Deduplicate the co-located manifest exports or update the spec-layer registration call.`,
|
|
1615
|
+
);
|
|
1616
|
+
}
|
|
1617
|
+
registeredCustomBatchManifests.set(manifest.batchRef, manifest);
|
|
1618
|
+
}
|
|
1619
|
+
}
|
|
1620
|
+
|
|
1621
|
+
/**
|
|
1622
|
+
* Per-arm structural validation for a {@link CustomBatchManifest} at
|
|
1623
|
+
* registration time. Mirrors the discriminated union split in
|
|
1624
|
+
* `ExecutionContextCreatorBackendService.createForInternalCustomBatch`:
|
|
1625
|
+
*
|
|
1626
|
+
* - `resource_anchored` — must declare a non-empty `resourceIdentifier`.
|
|
1627
|
+
* The spec layer does not (and should not) try to verify that the
|
|
1628
|
+
* identifier resolves to a registered resource — that cross-check lives
|
|
1629
|
+
* inside the runtime EC creator where the resources registry is the
|
|
1630
|
+
* source of truth and where a missing resource fails closed with the
|
|
1631
|
+
* same error message authors already see today.
|
|
1632
|
+
* - `scope_anchored` — must declare a `primaryScope` that is a member of
|
|
1633
|
+
* {@link ResourcePrimaryScope} (the runtime synthetic operation copies
|
|
1634
|
+
* this value into `resourcePrimaryScope`, so a typo would silently
|
|
1635
|
+
* widen or narrow downstream authorization). The `operationIdentifier`
|
|
1636
|
+
* must follow the `<domain>:<batch-ref>` convention so synthetic
|
|
1637
|
+
* operation labels stay grep-able alongside their batch ref — the
|
|
1638
|
+
* convention is also pinned by a dedicated unit test.
|
|
1639
|
+
*
|
|
1640
|
+
* Adding a future arm to {@link CustomBatchManifest} is a compile-time
|
|
1641
|
+
* error in the exhaustive `default` branch, forcing the author to extend
|
|
1642
|
+
* the per-arm rules instead of leaking an unchecked manifest into the
|
|
1643
|
+
* registry.
|
|
1644
|
+
*/
|
|
1645
|
+
function assertCustomBatchManifestKindArm(manifest: CustomBatchManifest): void {
|
|
1646
|
+
switch (manifest.kind) {
|
|
1647
|
+
case CustomBatchManifestKind.RESOURCE_ANCHORED: {
|
|
1648
|
+
if (!manifest.resourceIdentifier || !manifest.resourceIdentifier.trim()) {
|
|
1649
|
+
throw new Error(
|
|
1650
|
+
`registerCustomBatchManifests(): resource_anchored manifest for "${manifest.batchRef}" must declare a non-empty trimmed \`resourceIdentifier\`.`,
|
|
1651
|
+
);
|
|
1652
|
+
}
|
|
1653
|
+
return;
|
|
1654
|
+
}
|
|
1655
|
+
case CustomBatchManifestKind.SCOPE_ANCHORED: {
|
|
1656
|
+
const allowedPrimaryScopes = Object.values(ResourcePrimaryScope) as readonly string[];
|
|
1657
|
+
if (!allowedPrimaryScopes.includes(manifest.primaryScope)) {
|
|
1658
|
+
throw new Error(
|
|
1659
|
+
`registerCustomBatchManifests(): scope_anchored manifest for "${manifest.batchRef}" declares unknown primaryScope "${manifest.primaryScope}". Use one of: ${allowedPrimaryScopes.join(', ')}.`,
|
|
1660
|
+
);
|
|
1661
|
+
}
|
|
1662
|
+
const colonIndex = manifest.operationIdentifier.indexOf(':');
|
|
1663
|
+
const domain = colonIndex >= 0 ? manifest.operationIdentifier.slice(0, colonIndex).trim() : '';
|
|
1664
|
+
const tail = colonIndex >= 0 ? manifest.operationIdentifier.slice(colonIndex + 1).trim() : '';
|
|
1665
|
+
if (colonIndex < 0 || !domain || tail !== manifest.batchRef) {
|
|
1666
|
+
throw new Error(
|
|
1667
|
+
`registerCustomBatchManifests(): scope_anchored manifest for "${manifest.batchRef}" must use the "<domain>:${manifest.batchRef}" convention for \`operationIdentifier\` (got "${manifest.operationIdentifier}"). Pick a non-empty domain prefix (e.g. "notifications") so synthetic operation labels stay grep-able alongside their batch ref.`,
|
|
1668
|
+
);
|
|
1669
|
+
}
|
|
1670
|
+
return;
|
|
1671
|
+
}
|
|
1672
|
+
default: {
|
|
1673
|
+
const exhaustiveCheck: never = manifest;
|
|
1674
|
+
throw new Error(
|
|
1675
|
+
`registerCustomBatchManifests(): unsupported CustomBatchManifest kind: ${JSON.stringify(exhaustiveCheck)}.`,
|
|
1676
|
+
);
|
|
1677
|
+
}
|
|
1678
|
+
}
|
|
1679
|
+
}
|
|
1680
|
+
|
|
1681
|
+
/**
|
|
1682
|
+
* Test-only helper that wipes the module-local custom-batch manifest registry.
|
|
1683
|
+
* Authored specifications should never call this at runtime — it exists only
|
|
1684
|
+
* so tests can exercise registration / cross-validation in isolation.
|
|
1685
|
+
*/
|
|
1686
|
+
export function resetCustomBatchManifestRegistryForTesting(): void {
|
|
1687
|
+
registeredCustomBatchManifests.clear();
|
|
1688
|
+
}
|
|
1689
|
+
|
|
1690
|
+
/**
|
|
1691
|
+
* Structural equality for two {@link CustomBatchManifest} values, used by
|
|
1692
|
+
* {@link registerCustomBatchManifests} to detect divergent re-registration of
|
|
1693
|
+
* the same `batchRef` across the engine + app bootstrap seams.
|
|
1694
|
+
*
|
|
1695
|
+
* Comparison rules:
|
|
1696
|
+
* - Both manifests must declare the same `kind` discriminator. A
|
|
1697
|
+
* `resource_anchored` manifest is **never** equal to a `scope_anchored`
|
|
1698
|
+
* one even if their non-arm fields happen to align — the two arms model
|
|
1699
|
+
* structurally different bootstrap semantics in
|
|
1700
|
+
* `ExecutionContextCreatorBackendService.createForInternalCustomBatch` and
|
|
1701
|
+
* silently treating them as interchangeable would mask a real authoring
|
|
1702
|
+
* bug at registration time.
|
|
1703
|
+
* - Common fields (`batchRef`, `operationIdentifier`, `cronExpression`,
|
|
1704
|
+
* `cronExpressionConfigurable`) must match across both arms.
|
|
1705
|
+
* - The arm-specific identity field is then compared:
|
|
1706
|
+
* `resourceIdentifier` for `resource_anchored`, `primaryScope` for
|
|
1707
|
+
* `scope_anchored`. The exhaustive switch makes adding a future arm a
|
|
1708
|
+
* compile-time error here rather than a silent equality regression.
|
|
1709
|
+
*/
|
|
1710
|
+
function areCustomBatchManifestsEqual(a: CustomBatchManifest, b: CustomBatchManifest): boolean {
|
|
1711
|
+
if (a.kind !== b.kind) {
|
|
1712
|
+
return false;
|
|
1713
|
+
}
|
|
1714
|
+
const commonEqual =
|
|
1715
|
+
a.batchRef === b.batchRef
|
|
1716
|
+
&& a.operationIdentifier === b.operationIdentifier
|
|
1717
|
+
&& a.cronExpression === b.cronExpression
|
|
1718
|
+
&& Boolean(a.cronExpressionConfigurable) === Boolean(b.cronExpressionConfigurable);
|
|
1719
|
+
if (!commonEqual) {
|
|
1720
|
+
return false;
|
|
1721
|
+
}
|
|
1722
|
+
switch (a.kind) {
|
|
1723
|
+
case CustomBatchManifestKind.RESOURCE_ANCHORED:
|
|
1724
|
+
return a.resourceIdentifier
|
|
1725
|
+
=== (b as ResourceAnchoredCustomBatchManifest).resourceIdentifier;
|
|
1726
|
+
case CustomBatchManifestKind.SCOPE_ANCHORED:
|
|
1727
|
+
return a.primaryScope
|
|
1728
|
+
=== (b as ScopeAnchoredCustomBatchManifest).primaryScope;
|
|
1729
|
+
default: {
|
|
1730
|
+
const exhaustiveCheck: never = a;
|
|
1731
|
+
throw new Error(
|
|
1732
|
+
`areCustomBatchManifestsEqual(): unsupported CustomBatchManifest kind: ${JSON.stringify(exhaustiveCheck)}.`,
|
|
1733
|
+
);
|
|
1734
|
+
}
|
|
1735
|
+
}
|
|
1736
|
+
}
|
|
1737
|
+
|
|
1738
|
+
/**
|
|
1739
|
+
* Validation entry point used by the resource specification factory to assert
|
|
1740
|
+
* that an authored `scheduledExecution` block is internally consistent and,
|
|
1741
|
+
* for custom-batch arms, cross-checks against the declarative
|
|
1742
|
+
* {@link CustomBatchManifest} registry so typos or unregistered refs fail at
|
|
1743
|
+
* module load rather than silently at runtime.
|
|
1744
|
+
*
|
|
1745
|
+
* Each arm of the discriminated union enforces its own fail-closed contract:
|
|
1746
|
+
* - `NATIVE_CRON_JOB`: `cronExpression` must be a non-empty trimmed string.
|
|
1747
|
+
* - `NATIVE_BATCH_JOB`: no schedule or batch ref is permitted.
|
|
1748
|
+
* - `CUSTOM_BATCH`: `customBatchRef` must resolve to a registered manifest;
|
|
1749
|
+
* when the manifest declares a fixed cron the spec must echo it; when the
|
|
1750
|
+
* manifest is `cronExpressionConfigurable: true` the spec only needs to
|
|
1751
|
+
* carry a non-empty cron (divergence from the manifest default is allowed
|
|
1752
|
+
* because the runtime cron comes from app config); when the manifest omits
|
|
1753
|
+
* a cron entirely the spec must omit it too.
|
|
1754
|
+
*
|
|
1755
|
+
* Cross-validation is opt-in by design: the spec layer is built around a
|
|
1756
|
+
* declarative `CustomBatchManifest` registry seeded by the engine (and
|
|
1757
|
+
* optionally by app bootstraps) rather than an imperative dependency on
|
|
1758
|
+
* runtime service instances. If no manifest has been registered for a
|
|
1759
|
+
* `customBatchRef`, validation fails closed with an actionable message.
|
|
1760
|
+
*
|
|
1761
|
+
* **Test-suite seeding contract.** The framework registers built-in batches
|
|
1762
|
+
* when the public package entry is imported. Test files that
|
|
1763
|
+
* (a) reset the registry via {@link resetCustomBatchManifestRegistryForTesting}
|
|
1764
|
+
* and (b) need engine batches available afterwards must re-seed by calling
|
|
1765
|
+
* `registerCustomBatchManifests(ENGINE_CUSTOM_BATCH_MANIFESTS)` in `beforeAll`
|
|
1766
|
+
* or `beforeEach`. The current test suites either scope their reset to
|
|
1767
|
+
* test-only manifests or never reach built-in batches, so this remains an
|
|
1768
|
+
* explicit test setup contract.
|
|
1769
|
+
*
|
|
1770
|
+
* @param ownerLabel Stable identifier of the owning operation (used in error
|
|
1771
|
+
* messages so authors can locate the broken spec immediately).
|
|
1772
|
+
*/
|
|
1773
|
+
export function validateResourceOperationScheduledExecutionSpecification(
|
|
1774
|
+
ownerLabel: string,
|
|
1775
|
+
scheduledExecution: ResourceOperationScheduledExecutionSpecification | undefined,
|
|
1776
|
+
): void {
|
|
1777
|
+
if (!scheduledExecution) {
|
|
1778
|
+
return;
|
|
1779
|
+
}
|
|
1780
|
+
assertNonEmptyScheduledExecutionProseSlot(ownerLabel, 'purpose', scheduledExecution.purpose);
|
|
1781
|
+
assertNonEmptyScheduledExecutionProseSlot(ownerLabel, 'outcome', scheduledExecution.outcome);
|
|
1782
|
+
assertOptionalNonEmptyProseSlot(
|
|
1783
|
+
ownerLabel,
|
|
1784
|
+
'scheduledExecution.useWhen',
|
|
1785
|
+
scheduledExecution.useWhen,
|
|
1786
|
+
);
|
|
1787
|
+
assertOptionalNonEmptyProseSlot(
|
|
1788
|
+
ownerLabel,
|
|
1789
|
+
'scheduledExecution.avoidWhen',
|
|
1790
|
+
scheduledExecution.avoidWhen,
|
|
1791
|
+
);
|
|
1792
|
+
assertOptionalNonEmptyStringList(
|
|
1793
|
+
ownerLabel,
|
|
1794
|
+
'scheduledExecution.businessConstraints',
|
|
1795
|
+
scheduledExecution.businessConstraints,
|
|
1796
|
+
);
|
|
1797
|
+
assertOptionalNonEmptyStringList(
|
|
1798
|
+
ownerLabel,
|
|
1799
|
+
'scheduledExecution.codeHandling.notes',
|
|
1800
|
+
scheduledExecution.codeHandling?.notes,
|
|
1801
|
+
);
|
|
1802
|
+
|
|
1803
|
+
switch (scheduledExecution.variantType) {
|
|
1804
|
+
case ResourceOperationScheduledExecutionVariantType.NATIVE_CRON_JOB:
|
|
1805
|
+
assertNativeCronJobArm(ownerLabel, scheduledExecution);
|
|
1806
|
+
return;
|
|
1807
|
+
case ResourceOperationScheduledExecutionVariantType.NATIVE_BATCH_JOB:
|
|
1808
|
+
assertNativeBatchJobArm(ownerLabel, scheduledExecution);
|
|
1809
|
+
return;
|
|
1810
|
+
case ResourceOperationScheduledExecutionVariantType.CUSTOM_BATCH:
|
|
1811
|
+
assertCustomBatchArm(ownerLabel, scheduledExecution);
|
|
1812
|
+
return;
|
|
1813
|
+
default: {
|
|
1814
|
+
const exhaustiveCheck: never = scheduledExecution;
|
|
1815
|
+
throw new Error(
|
|
1816
|
+
`Resource operation "${ownerLabel}" scheduledExecution carries an unsupported variantType: ${JSON.stringify(exhaustiveCheck)}.`,
|
|
1817
|
+
);
|
|
1818
|
+
}
|
|
1819
|
+
}
|
|
1820
|
+
}
|
|
1821
|
+
|
|
1822
|
+
function assertNonEmptyScheduledExecutionProseSlot(
|
|
1823
|
+
ownerLabel: string,
|
|
1824
|
+
slotLabel: 'purpose' | 'outcome',
|
|
1825
|
+
value: string | undefined,
|
|
1826
|
+
): void {
|
|
1827
|
+
if (!value || !value.trim()) {
|
|
1828
|
+
throw new Error(
|
|
1829
|
+
`Resource operation "${ownerLabel}" scheduledExecution.${slotLabel} must be a non-empty prose slot so companion prompts have grounded cron-run semantics.`,
|
|
1830
|
+
);
|
|
1831
|
+
}
|
|
1832
|
+
}
|
|
1833
|
+
|
|
1834
|
+
/**
|
|
1835
|
+
* Defense-in-depth runtime guards for the NATIVE_CRON_JOB arm.
|
|
1836
|
+
*
|
|
1837
|
+
* The static type already requires `cronExpression: string` and does **not**
|
|
1838
|
+
* declare `customBatchRef`, so well-typed authoring sites cannot reach an
|
|
1839
|
+
* invalid state. We still trim-check `cronExpression` and structurally reject
|
|
1840
|
+
* a smuggled `customBatchRef` so authoring sites that bypass type narrowing
|
|
1841
|
+
* (`as never`, `as any`, dynamic data, custom factories) cannot leak a blank
|
|
1842
|
+
* schedule or a foreign field into companion prompts. Symmetric with
|
|
1843
|
+
* {@link assertNativeBatchJobArm} so every arm enforces the same defensive
|
|
1844
|
+
* discipline.
|
|
1845
|
+
*/
|
|
1846
|
+
function assertNativeCronJobArm(
|
|
1847
|
+
ownerLabel: string,
|
|
1848
|
+
arm: NativeCronJobScheduledExecutionSpecification,
|
|
1849
|
+
): void {
|
|
1850
|
+
if (!arm.cronExpression || !arm.cronExpression.trim()) {
|
|
1851
|
+
throw new Error(
|
|
1852
|
+
`Resource operation "${ownerLabel}" scheduledExecution.cronExpression must be a non-empty trimmed cron expression for the NATIVE_CRON_JOB arm (the runtime CRON_JOB variant requires a concrete schedule).`,
|
|
1853
|
+
);
|
|
1854
|
+
}
|
|
1855
|
+
if ('customBatchRef' in arm && (arm as unknown as { customBatchRef?: unknown }).customBatchRef !== undefined) {
|
|
1856
|
+
throw new Error(
|
|
1857
|
+
`Resource operation "${ownerLabel}" scheduledExecution cannot declare customBatchRef for the NATIVE_CRON_JOB arm — custom batches belong to the CUSTOM_BATCH arm so the declarative manifest cross-validation runs.`,
|
|
1858
|
+
);
|
|
1859
|
+
}
|
|
1860
|
+
}
|
|
1861
|
+
|
|
1862
|
+
/**
|
|
1863
|
+
* Defense-in-depth runtime guards for the NATIVE_BATCH_JOB arm.
|
|
1864
|
+
*
|
|
1865
|
+
* The static type does **not** declare `cronExpression` or `customBatchRef`,
|
|
1866
|
+
* so well-typed authoring sites cannot reach this state. The structural
|
|
1867
|
+
* `'<key>' in arm` checks back the `// @ts-expect-error` test cases and
|
|
1868
|
+
* protect against dynamic data or `as any` bypasses at authoring sites — if
|
|
1869
|
+
* an author silences TypeScript to attach a stray field to a batch-job arm,
|
|
1870
|
+
* the validator still rejects it at module load.
|
|
1871
|
+
*/
|
|
1872
|
+
function assertNativeBatchJobArm(
|
|
1873
|
+
ownerLabel: string,
|
|
1874
|
+
arm: NativeBatchJobScheduledExecutionSpecification,
|
|
1875
|
+
): void {
|
|
1876
|
+
if ('cronExpression' in arm && (arm as unknown as { cronExpression?: unknown }).cronExpression !== undefined) {
|
|
1877
|
+
throw new Error(
|
|
1878
|
+
`Resource operation "${ownerLabel}" scheduledExecution cannot declare cronExpression for the NATIVE_BATCH_JOB arm — batch-job variants are event-triggered and never carry a cron. Move the schedule to the NATIVE_CRON_JOB or CUSTOM_BATCH arm.`,
|
|
1879
|
+
);
|
|
1880
|
+
}
|
|
1881
|
+
if ('customBatchRef' in arm && (arm as unknown as { customBatchRef?: unknown }).customBatchRef !== undefined) {
|
|
1882
|
+
throw new Error(
|
|
1883
|
+
`Resource operation "${ownerLabel}" scheduledExecution cannot declare customBatchRef for the NATIVE_BATCH_JOB arm — custom batches belong to the CUSTOM_BATCH arm so the declarative manifest and cron echo stay consistent.`,
|
|
1884
|
+
);
|
|
1885
|
+
}
|
|
1886
|
+
}
|
|
1887
|
+
|
|
1888
|
+
/**
|
|
1889
|
+
* Validates the CUSTOM_BATCH arm against the spec-layer manifest registry.
|
|
1890
|
+
*
|
|
1891
|
+
* Cron-echo policy:
|
|
1892
|
+
* - **Fixed-cron manifest** (`cronExpressionConfigurable !== true` and
|
|
1893
|
+
* `cronExpression` declared): the authored spec must echo the manifest's
|
|
1894
|
+
* cron exactly, so companion prompts and the runtime cannot drift.
|
|
1895
|
+
* - **Configurable-cron manifest** (`cronExpressionConfigurable === true`):
|
|
1896
|
+
* the authored spec must still carry a non-empty cron (companion prompts
|
|
1897
|
+
* need a cadence) but is free to diverge from the manifest's runtime
|
|
1898
|
+
* default — divergence is the whole point of configurability.
|
|
1899
|
+
* - **Event-triggered manifest** (`cronExpression` undefined): the spec
|
|
1900
|
+
* must omit `cronExpression` so it does not invent a schedule the runtime
|
|
1901
|
+
* never honors.
|
|
1902
|
+
*/
|
|
1903
|
+
function assertCustomBatchArm(
|
|
1904
|
+
ownerLabel: string,
|
|
1905
|
+
arm: CustomBatchScheduledExecutionSpecification,
|
|
1906
|
+
): void {
|
|
1907
|
+
if (!arm.customBatchRef || !arm.customBatchRef.trim()) {
|
|
1908
|
+
throw new Error(
|
|
1909
|
+
`Resource operation "${ownerLabel}" scheduledExecution.customBatchRef must be a non-empty trimmed batch ref for the CUSTOM_BATCH arm (for example "files-cleanup").`,
|
|
1910
|
+
);
|
|
1911
|
+
}
|
|
1912
|
+
if (
|
|
1913
|
+
'cronExpression' in arm
|
|
1914
|
+
&& arm.cronExpression !== undefined
|
|
1915
|
+
&& (!arm.cronExpression || !arm.cronExpression.trim())
|
|
1916
|
+
) {
|
|
1917
|
+
throw new Error(
|
|
1918
|
+
`Resource operation "${ownerLabel}" scheduledExecution.cronExpression must be a non-empty trimmed cron expression when provided (authors must not declare an empty schedule).`,
|
|
1919
|
+
);
|
|
1920
|
+
}
|
|
1921
|
+
|
|
1922
|
+
const manifest = registeredCustomBatchManifests.get(arm.customBatchRef);
|
|
1923
|
+
if (!manifest) {
|
|
1924
|
+
throw new Error(
|
|
1925
|
+
`Resource operation "${ownerLabel}" scheduledExecution.customBatchRef "${arm.customBatchRef}" is not registered. Either export a CustomBatchManifest next to the batch factory (engine batches go through ENGINE_CUSTOM_BATCH_MANIFESTS) and call registerCustomBatchManifests() before this spec loads, or correct the ref.`,
|
|
1926
|
+
);
|
|
1927
|
+
}
|
|
1928
|
+
if (manifest.cronExpression && !arm.cronExpression) {
|
|
1929
|
+
throw new Error(
|
|
1930
|
+
`Resource operation "${ownerLabel}" scheduledExecution.cronExpression must echo the runtime cron "${manifest.cronExpression}" declared by custom batch "${arm.customBatchRef}" so companion prompts see the authoritative cadence.`,
|
|
1931
|
+
);
|
|
1932
|
+
}
|
|
1933
|
+
if (!manifest.cronExpression && arm.cronExpression) {
|
|
1934
|
+
throw new Error(
|
|
1935
|
+
`Resource operation "${ownerLabel}" scheduledExecution.cronExpression is declared but custom batch "${arm.customBatchRef}" is registered without a cron (event-triggered). Remove the authored cron or update the manifest if the runtime actually schedules this batch.`,
|
|
1936
|
+
);
|
|
1937
|
+
}
|
|
1938
|
+
if (
|
|
1939
|
+
manifest.cronExpression
|
|
1940
|
+
&& arm.cronExpression
|
|
1941
|
+
&& !manifest.cronExpressionConfigurable
|
|
1942
|
+
&& manifest.cronExpression !== arm.cronExpression
|
|
1943
|
+
) {
|
|
1944
|
+
throw new Error(
|
|
1945
|
+
`Resource operation "${ownerLabel}" scheduledExecution.cronExpression "${arm.cronExpression}" does not match the manifest cron "${manifest.cronExpression}" for custom batch "${arm.customBatchRef}". Align the authored cron with the runtime batchCronjob_Context, or mark the manifest as cronExpressionConfigurable if the schedule is intentionally driven by app config.`,
|
|
1946
|
+
);
|
|
1947
|
+
}
|
|
1948
|
+
}
|
|
1949
|
+
|
|
1950
|
+
/**
|
|
1951
|
+
* Iterate an operation map and validate every authored `scheduledExecution`
|
|
1952
|
+
* block. Same dual-seam rationale as communications: base-operation and
|
|
1953
|
+
* frontend-operation both structurally carry the slot, and both seams must
|
|
1954
|
+
* fail closed at module load.
|
|
1955
|
+
*/
|
|
1956
|
+
function validateResourceOperationsScheduledExecution(
|
|
1957
|
+
ownerLabelPrefix: string,
|
|
1958
|
+
operations:
|
|
1959
|
+
| Record<string, ResourceOperationSpecification | ResourceFrontendViewSpecification | undefined>
|
|
1960
|
+
| undefined,
|
|
1961
|
+
): void {
|
|
1962
|
+
if (!operations) {
|
|
1963
|
+
return;
|
|
1964
|
+
}
|
|
1965
|
+
for (const [operationId, operationSpec] of Object.entries(operations)) {
|
|
1966
|
+
if (!operationSpec) {
|
|
1967
|
+
continue;
|
|
1968
|
+
}
|
|
1969
|
+
validateResourceOperationScheduledExecutionSpecification(
|
|
1970
|
+
`${ownerLabelPrefix}${operationId}`,
|
|
1971
|
+
operationSpec.scheduledExecution,
|
|
1972
|
+
);
|
|
1973
|
+
}
|
|
1974
|
+
}
|
|
1975
|
+
|
|
1976
|
+
export type ResourceOperationSpecificationMap<
|
|
1977
|
+
TCustomOp extends EnumLikeType | undefined = any,
|
|
1978
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
|
|
1979
|
+
> = Partial<Record<ValidOperationKeys<TCustomOp, TCoreOp>, ResourceOperationSpecification>>;
|
|
1980
|
+
```
|
|
1981
|
+
## Import Origins
|
|
1982
|
+
|
|
1983
|
+
- `@wildo-ai/saas-specifications`
|
|
1984
|
+
|
|
1985
|
+
## Source Excerpts
|
|
1986
|
+
|
|
1987
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
1988
|
+
|
|
1989
|
+
```typescript
|
|
1990
|
+
*
|
|
1991
|
+
* Frontend aspect distilled from `ResourceUIBehavior` for specification / companion layers.
|
|
1992
|
+
*/
|
|
1993
|
+
export interface ResourceFrontendLabelAspect {
|
|
1994
|
+
strategy: 'field-paths' | 'computed';
|
|
1995
|
+
fieldNames?: string[];
|
|
1996
|
+
}
|
|
1997
|
+
|
|
1998
|
+
export interface ResourceFrontendLayoutAspect {
|
|
1999
|
+
refs?: LayoutRefManifest;
|
|
2000
|
+
hasDisplayTemplate: boolean;
|
|
2001
|
+
hasSummaryTemplate: boolean;
|
|
2002
|
+
hasEditTemplate: boolean;
|
|
2003
|
+
}
|
|
2004
|
+
|
|
2005
|
+
export interface ResourceFrontendConfigurationAspect<
|
|
2006
|
+
TCustomOp extends EnumLikeType | undefined,
|
|
2007
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined,
|
|
2008
|
+
TSchema extends z.ZodTypeAny,
|
|
2009
|
+
> {
|
|
2010
|
+
schema: TSchema;
|
|
2011
|
+
label?: ResourceFrontendLabelAspect;
|
|
2012
|
+
emptyState?: ResourceUIBehavior_EmptyState;
|
|
2013
|
+
layout?: ResourceFrontendLayoutAspect;
|
|
2014
|
+
guidance?: Record<string, ResourceUIBehavior_GuidanceFlow>;
|
|
2015
|
+
relationshipOverrides?: NonNullable<ResourceUIBehaviorConfig<TCustomOp, TCoreOp, TSchema>['relationshipOverrides']>;
|
|
2016
|
+
surfacedOperations: ResourceSpecificationSurfacedOperationMap<TCustomOp, TCoreOp>;
|
|
2017
|
+
operations: ResourceFrontendOperationSurfaceMap<TCustomOp, TCoreOp>;
|
|
2018
|
+
}
|
|
2019
|
+
```
|
|
2020
|
+
## Import Origins
|
|
2021
|
+
|
|
2022
|
+
- `@wildo-ai/saas-specifications`
|
|
2023
|
+
|
|
2024
|
+
## Source Excerpts
|
|
2025
|
+
|
|
2026
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
2027
|
+
|
|
2028
|
+
```typescript
|
|
2029
|
+
*
|
|
2030
|
+
* Prose slots for resource specification `frontend` slice (label, layout, empty state, guidance, operations).
|
|
2031
|
+
*/
|
|
2032
|
+
export interface ResourceFrontendLabelSpecification {
|
|
2033
|
+
purpose: string;
|
|
2034
|
+
textSlots?: TranslationSlotSpecificationMap;
|
|
2035
|
+
}
|
|
2036
|
+
|
|
2037
|
+
export type ResourceFrontendStructuralSlotSpecification = StructuralTranslationSlotSpecification;
|
|
2038
|
+
|
|
2039
|
+
export interface ResourceFrontendLayoutSpecification {
|
|
2040
|
+
purpose?: string;
|
|
2041
|
+
displayPurpose?: string;
|
|
2042
|
+
summaryPurpose?: string;
|
|
2043
|
+
editPurpose?: string;
|
|
2044
|
+
/**
|
|
2045
|
+
* Intent of the resource's `layout.header` template — the record's IDENTITY
|
|
2046
|
+
* LINE in the READ page header (accent swatch / name / status / visibility
|
|
2047
|
+
* chips, in whatever order the resource composes them).
|
|
2048
|
+
*
|
|
2049
|
+
* Documented separately from `displayPurpose` because the two answer
|
|
2050
|
+
* different questions and, once a header template exists, must not repeat
|
|
2051
|
+
* each other: the header states WHICH record this is and what state it is in,
|
|
2052
|
+
* the display body states everything else about it.
|
|
2053
|
+
*/
|
|
2054
|
+
headerPurpose?: string;
|
|
2055
|
+
sections?: Record<string, ResourceFrontendStructuralSlotSpecification>;
|
|
2056
|
+
wizardSteps?: Record<string, ResourceFrontendStructuralSlotSpecification>;
|
|
2057
|
+
groups?: Record<string, ResourceFrontendStructuralSlotSpecification>;
|
|
2058
|
+
}
|
|
2059
|
+
|
|
2060
|
+
export interface ResourceFrontendEmptyStateSpecification {
|
|
2061
|
+
purpose: string;
|
|
2062
|
+
primaryActionPurpose?: string;
|
|
2063
|
+
secondaryActionPurpose?: string;
|
|
2064
|
+
}
|
|
2065
|
+
|
|
2066
|
+
export interface ResourceFrontendGuidanceFlowSpecification {
|
|
2067
|
+
purpose: string;
|
|
2068
|
+
whenToTrigger?: string;
|
|
2069
|
+
textSlots?: TranslationSlotSpecificationMap;
|
|
2070
|
+
elements?: Record<string, {
|
|
2071
|
+
purpose: string;
|
|
2072
|
+
whenToUse?: string;
|
|
2073
|
+
textSlots?: TranslationSlotSpecificationMap;
|
|
2074
|
+
}>;
|
|
2075
|
+
}
|
|
2076
|
+
|
|
2077
|
+
/**
|
|
2078
|
+
* Which separate view family an operation links to in addition to its main host.
|
|
2079
|
+
*
|
|
2080
|
+
* These families will later gain their own dedicated DTO registries; the
|
|
2081
|
+
* resource specification keeps the operation-owned linkage close to the
|
|
2082
|
+
* resource/runtime seam for now.
|
|
2083
|
+
*/
|
|
2084
|
+
export enum ResourceOperationOtherViewKind {
|
|
2085
|
+
EXECUTION = 'execution',
|
|
2086
|
+
CHART = 'chart',
|
|
2087
|
+
COMPOSITE = 'composite',
|
|
2088
|
+
FULL_CUSTOM = 'full-custom',
|
|
2089
|
+
}
|
|
2090
|
+
|
|
2091
|
+
/**
|
|
2092
|
+
* Resource-owned direct host override selected through
|
|
2093
|
+
* `operationFrontendConfig.customView`.
|
|
2094
|
+
*/
|
|
2095
|
+
export interface ResourceOperationCustomViewSpecification {
|
|
2096
|
+
/** Why this direct operation host exists beyond the default resource shell. */
|
|
2097
|
+
purpose: string;
|
|
2098
|
+
/** Situations where this host override is the intended authoring choice. */
|
|
2099
|
+
whenToUse?: string;
|
|
2100
|
+
/** Meaning of the host-level translatable slots such as title and description. */
|
|
2101
|
+
textSlots?: TranslationSlotSpecificationMap;
|
|
2102
|
+
/** Optional preset/base shell that the custom view composes or extends. */
|
|
2103
|
+
basedOnPreset?: string;
|
|
2104
|
+
/** Public symbol exposing the actual custom host component. */
|
|
2105
|
+
implementationSymbol: CodeSymbolRef;
|
|
2106
|
+
/** Preferred public import surface when different from the implementation. */
|
|
2107
|
+
consumerFacingSymbol?: CodeSymbolRef;
|
|
2108
|
+
/** Public declarations where this custom view is authored/selected. */
|
|
2109
|
+
declarationSymbols?: CodeSymbolRef[];
|
|
2110
|
+
/** Extra caveats for companion/transposer layers. */
|
|
2111
|
+
notes?: string[];
|
|
2112
|
+
}
|
|
2113
|
+
|
|
2114
|
+
/**
|
|
2115
|
+
* Additional non-host resource-owned views rendered inside a resource
|
|
2116
|
+
* operation host.
|
|
2117
|
+
*
|
|
2118
|
+
* These views are resolved by the framework directly from the resource UI
|
|
2119
|
+
* behavior's view declarations (`compositeViews[*].operationLike`,
|
|
2120
|
+
* `chartViews[*].operationLike`, `executionViews[*].surfaceInOperations`)
|
|
2121
|
+
* — there is no operation-level `additionalViews` authoring seam. The
|
|
2122
|
+
* specification layer simply mirrors, per operation, the set of resource-owned
|
|
2123
|
+
* views that target that operation host, for labelling/translation/authoring
|
|
2124
|
+
* documentation purposes.
|
|
2125
|
+
*/
|
|
2126
|
+
export interface ResourceOperationOtherViewSpecification {
|
|
2127
|
+
/** Stable referenced view identifier as declared by the resource UI behavior. */
|
|
2128
|
+
viewRef: string;
|
|
2129
|
+
/** Which view family owns the referenced view. */
|
|
2130
|
+
viewKind: ResourceOperationOtherViewKind;
|
|
2131
|
+
/** Why this extra linked view exists in the workflow. */
|
|
2132
|
+
purpose: string;
|
|
2133
|
+
/** Situations where the linked view should be used. */
|
|
2134
|
+
whenToUse?: string;
|
|
2135
|
+
/** Meaning of the linked-view translatable slots such as title and description. */
|
|
2136
|
+
textSlots?: TranslationSlotSpecificationMap;
|
|
2137
|
+
/** Extra caveats for companion/transposer layers. */
|
|
2138
|
+
notes?: string[];
|
|
2139
|
+
}
|
|
2140
|
+
|
|
2141
|
+
/**
|
|
2142
|
+
* Operation-owned view seams layered on top of the semantic operation meaning.
|
|
2143
|
+
*/
|
|
2144
|
+
export interface ResourceOperationViewSpecification {
|
|
2145
|
+
/** Direct replacement host selected through `customView`, if any. */
|
|
2146
|
+
customView?: ResourceOperationCustomViewSpecification;
|
|
2147
|
+
/** Additional linked views exposed alongside the main operation host. */
|
|
2148
|
+
otherViews?: ResourceOperationOtherViewSpecification[];
|
|
2149
|
+
}
|
|
2150
|
+
|
|
2151
|
+
/**
|
|
2152
|
+
* The frontend "view" of a single resource operation — the UI-side overlay
|
|
2153
|
+
* for an operation declared in `base.operations`.
|
|
2154
|
+
*
|
|
2155
|
+
* Structurally extends {@link ResourceOperationSpecification} so the same
|
|
2156
|
+
* intent/outcome/communications fields can be authored at this layer when
|
|
2157
|
+
* needed (the validators re-fire on every overlay seam — see
|
|
2158
|
+
* {@link resourceSpecificationFromFrontendConfiguration}). Adds variant
|
|
2159
|
+
* overlays and per-variant view-host configuration.
|
|
2160
|
+
*
|
|
2161
|
+
* Naming nuance: the inner `views?:` slot here is the *view-host* map (per
|
|
2162
|
+
* variant), distinct from the OUTER `frontend.views` map keyed by operation
|
|
2163
|
+
* id. Same word at two nesting levels — outer = "views by operation",
|
|
2164
|
+
* inner = "view-hosts by variant". Both are correct in their own right.
|
|
2165
|
+
*/
|
|
2166
|
+
export interface ResourceFrontendViewSpecification
|
|
2167
|
+
extends Omit<
|
|
2168
|
+
ResourceOperationSpecification,
|
|
2169
|
+
'variants' | 'responseStatuses' | 'errorScenarios' | 'idempotent' | 'rateLimitNote' | 'examples'
|
|
2170
|
+
> {
|
|
2171
|
+
/** Variant-specific UI semantics layered under the same logical operation id. */
|
|
2172
|
+
variants?: ResourceFrontendViewSpecificationVariants;
|
|
2173
|
+
/**
|
|
2174
|
+
* Per-variant view-host configuration (`customView`, `otherViews`).
|
|
2175
|
+
* The "view-hosts" of this view, in other words. Naming overlap with the
|
|
2176
|
+
* outer `frontend.views` map is intentional — see interface JSDoc.
|
|
2177
|
+
*/
|
|
2178
|
+
views?: {
|
|
2179
|
+
default?: ResourceOperationViewSpecification;
|
|
2180
|
+
variants?: Record<string, ResourceOperationViewSpecification>;
|
|
2181
|
+
};
|
|
2182
|
+
}
|
|
2183
|
+
|
|
2184
|
+
export type ResourceFrontendViewSpecificationMap<
|
|
2185
|
+
TCustomOp extends EnumLikeType | undefined = any,
|
|
2186
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
|
|
2187
|
+
> = Partial<Record<ValidOperationKeys<TCustomOp, TCoreOp>, ResourceFrontendViewSpecification>>;
|
|
2188
|
+
```
|
|
2189
|
+
## Import Origins
|
|
2190
|
+
|
|
2191
|
+
- `@wildo-ai/saas-specifications`
|
|
2192
|
+
|
|
2193
|
+
## Source Excerpts
|
|
2194
|
+
|
|
2195
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
2196
|
+
|
|
2197
|
+
```typescript
|
|
2198
|
+
*
|
|
2199
|
+
* Frontend-facing semantic additions layered on top of the base resource
|
|
2200
|
+
* specification.
|
|
2201
|
+
*
|
|
2202
|
+
* This slice is authored from a resolved `ResourceUIBehaviorConfig`, so it
|
|
2203
|
+
* should describe how the resource is surfaced to users, not restate structural
|
|
2204
|
+
* backend semantics that already live in the base specification.
|
|
2205
|
+
*/
|
|
2206
|
+
export type ResourceSpecificationFrontendConfig<
|
|
2207
|
+
TCustomOp extends EnumLikeType | undefined = any,
|
|
2208
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
|
|
2209
|
+
> = {
|
|
2210
|
+
/** Why this resource label strategy exists in surfaced UI. */
|
|
2211
|
+
label?: ResourceFrontendLabelSpecification;
|
|
2212
|
+
/** How the frontend layout organizes the resource meaning. */
|
|
2213
|
+
layout?: ResourceFrontendLayoutSpecification;
|
|
2214
|
+
/** Why the empty state is framed the way it is. */
|
|
2215
|
+
emptyState?: ResourceFrontendEmptyStateSpecification;
|
|
2216
|
+
/** Semantic intent of resource-owned guidance flows. */
|
|
2217
|
+
guidance?: Record<string, ResourceFrontendGuidanceFlowSpecification>;
|
|
2218
|
+
/**
|
|
2219
|
+
* Per-operation frontend overlays — the UI-side "views" of each domain
|
|
2220
|
+
* operation declared in `base.operations`.
|
|
2221
|
+
*
|
|
2222
|
+
* Keys are the same operation identifiers as `base.operations`. Each value
|
|
2223
|
+
* supplies frontend-specific prose (purpose, whenToUse, importance, variant
|
|
2224
|
+
* overlays) and view-host configuration. The base entry remains the domain
|
|
2225
|
+
* truth; this map says HOW that operation surfaces in the UI.
|
|
2226
|
+
*
|
|
2227
|
+
* Renamed from `operations` to `views` (April 2026): the previous name
|
|
2228
|
+
* suggested a duplicate domain-operations declaration, when the real intent
|
|
2229
|
+
* is "the views of the operations". The base operations map remains
|
|
2230
|
+
* `operations`; this UI overlay is `views`.
|
|
2231
|
+
*
|
|
2232
|
+
* Note on inner naming: each entry can declare a nested `views?:` slot that
|
|
2233
|
+
* holds per-variant view-host configuration (`customView`, `otherViews`).
|
|
2234
|
+
* The outer `views` (here) is "views BY operation"; the inner `views`
|
|
2235
|
+
* (inside each entry) is "view-hosts BY variant" — same word, different
|
|
2236
|
+
* nesting level, both correct in their own right.
|
|
2237
|
+
*/
|
|
2238
|
+
views?: ResourceFrontendViewSpecificationMap<TCustomOp, TCoreOp>;
|
|
2239
|
+
};
|
|
2240
|
+
```
|
|
2241
|
+
## Import Origins
|
|
2242
|
+
|
|
2243
|
+
- `@wildo-ai/saas-specifications`
|
|
2244
|
+
|
|
2245
|
+
## Source Excerpts
|
|
2246
|
+
|
|
2247
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
2248
|
+
|
|
2249
|
+
```typescript
|
|
2250
|
+
*
|
|
2251
|
+
* Import-oriented references that help downstream prompt/transposition layers
|
|
2252
|
+
* write truthful code against this resource.
|
|
2253
|
+
*/
|
|
2254
|
+
export interface ResourceSpecificationCodeHandling {
|
|
2255
|
+
/** Public schema symbol that owns the resource main shape. */
|
|
2256
|
+
mainSchema: CodeSymbolRef;
|
|
2257
|
+
/** Public factory symbol that owns the resource structural contract. */
|
|
2258
|
+
resourceFactory?: CodeSymbolRef;
|
|
2259
|
+
/** Truthful locator when the resource factory lives inside a public collection export. */
|
|
2260
|
+
resourceFactoryCollectionEntry?: CodeCollectionEntryRef;
|
|
2261
|
+
/**
|
|
2262
|
+
* Public enum member representing this resource type.
|
|
2263
|
+
* Required: every resource specification identifies the same public resource
|
|
2264
|
+
* enum member used by its runtime factory. This lets coding and companion
|
|
2265
|
+
* workflows generate discriminated resource logic without guessing or
|
|
2266
|
+
* silently dropping the resource identity.
|
|
2267
|
+
*/
|
|
2268
|
+
resourceType: CodeEnumMemberRef;
|
|
2269
|
+
/**
|
|
2270
|
+
* Public enums that define the operation identifier vocabulary.
|
|
2271
|
+
* Required whenever the resource has operations. Coding and companion
|
|
2272
|
+
* workflows use `coreEnum` / `customEnum` as the authoritative vocabulary
|
|
2273
|
+
* for emitted operation branches, so the declaration must be complete rather
|
|
2274
|
+
* than leaving the runtime to infer missing cases.
|
|
2275
|
+
*/
|
|
2276
|
+
operationVocabulary: ResourceSpecificationOperationVocabulary;
|
|
2277
|
+
/**
|
|
2278
|
+
* Public frontend contribution symbols used to build the merged
|
|
2279
|
+
* `resourceFrontendConfiguration()` input.
|
|
2280
|
+
*/
|
|
2281
|
+
frontendConfigurationSources?: CodeSymbolRef[];
|
|
2282
|
+
/** Truthful locators when frontend UI behavior leaves live inside public collections. */
|
|
2283
|
+
frontendConfigurationSourceEntries?: CodeCollectionEntryRef[];
|
|
2284
|
+
/** Extra caveats for downstream coding/transposition consumers. */
|
|
2285
|
+
notes?: string[];
|
|
2286
|
+
}
|
|
2287
|
+
```
|
|
2288
|
+
## Import Origins
|
|
2289
|
+
|
|
2290
|
+
- `@wildo-ai/saas-specifications`
|
|
2291
|
+
|
|
2292
|
+
## Source Excerpts
|
|
2293
|
+
|
|
2294
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
2295
|
+
|
|
2296
|
+
```typescript
|
|
2297
|
+
*
|
|
2298
|
+
* Callback parameter type for `resourceSpecification()`.
|
|
2299
|
+
*
|
|
2300
|
+
* Mirrors `ResourceUIBehaviorCallbackParams` — the factory resolves the schema
|
|
2301
|
+
* shape so that `{primitive}Spec()` decorators can be called with type safety.
|
|
2302
|
+
*/
|
|
2303
|
+
export type ResourceSpecificationCallbackParams<
|
|
2304
|
+
TCustomOp extends EnumLikeType | undefined,
|
|
2305
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined,
|
|
2306
|
+
TSchema extends z.ZodTypeAny,
|
|
2307
|
+
> = {
|
|
2308
|
+
/** The raw Zod schema (e.g., `TodoSchema`). */
|
|
2309
|
+
schema: TSchema;
|
|
2310
|
+
/** Pre-resolved shape — each key is a schema field ready for decorator chaining. */
|
|
2311
|
+
schemaShape: ObjectShape<TSchema>;
|
|
2312
|
+
};
|
|
2313
|
+
|
|
2314
|
+
/**
|
|
2315
|
+
* Return type of the base `resourceSpecification()` callback.
|
|
2316
|
+
*
|
|
2317
|
+
* Resource-level prose lives here alongside the per-field decorator container.
|
|
2318
|
+
* The `fields` property works identically to `ResourceUIBehaviorConfig.fields`:
|
|
2319
|
+
* calling `{primitive}Spec()` on a shape field mutates its metadata in place;
|
|
2320
|
+
* the property itself exists for type safety and declaration.
|
|
2321
|
+
*
|
|
2322
|
+
* **Validator-entry contract — read this before constructing this object
|
|
2323
|
+
* directly (M5-9).** The cross-cutting fail-closed validators that protect
|
|
2324
|
+
* spec → runtime parity (`validateResourceOperationsCommunications`,
|
|
2325
|
+
* `validateResourceOperationsScheduledExecution`, and the per-delivery,
|
|
2326
|
+
* per-slot, per-field assertions they fan out to) ONLY fire from inside
|
|
2327
|
+
* the two authoring factories:
|
|
2328
|
+
*
|
|
2329
|
+
* 1. {@link resourceSpecification} — runs the validators on
|
|
2330
|
+
* `config.operations` and `config.frontend?.views` after the
|
|
2331
|
+
* callback returns.
|
|
2332
|
+
* 2. {@link resourceSpecificationFromFrontendConfiguration} — runs the
|
|
2333
|
+
* validators on `base.operations`, `base.frontend?.views`, and the
|
|
2334
|
+
* callback's `frontend.views` (the `base` revalidation forecloses
|
|
2335
|
+
* a hand-built-base regression silently bypassing the contract).
|
|
2336
|
+
*
|
|
2337
|
+
* If a future caller constructs a `ResourceSpecificationConfig` literal
|
|
2338
|
+
* by hand and exports it WITHOUT routing it through one of those two
|
|
2339
|
+
* factories, NONE of the per-delivery / per-slot / per-channel uniqueness
|
|
2340
|
+
* / system-email cross-link / m2m runtime-identity / M2MNotificationLevel
|
|
2341
|
+
* enum-membership / scheduledExecution custom-batch cross-link checks
|
|
2342
|
+
* will run — the spec would compile and ship, and the dispatch-side
|
|
2343
|
+
* contract violations would only surface as runtime errors at companion
|
|
2344
|
+
* render time or, worse, at user-facing dispatch time. Always author via
|
|
2345
|
+
* the two factories above; treat this type as the factory return shape,
|
|
2346
|
+
* not as a raw spec authoring surface.
|
|
2347
|
+
*/
|
|
2348
|
+
export type ResourceSpecificationConfig<
|
|
2349
|
+
TCustomOp extends EnumLikeType | undefined = any,
|
|
2350
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
|
|
2351
|
+
TSchema extends z.ZodTypeAny = z.ZodAny,
|
|
2352
|
+
> = {
|
|
2353
|
+
/** Why this resource exists in the domain. */
|
|
2354
|
+
purpose: string;
|
|
2355
|
+
/** Functional role played by the resource inside the business architecture. */
|
|
2356
|
+
businessRole: string;
|
|
2357
|
+
/** How the resource evolves over time (lifecycle semantics). */
|
|
2358
|
+
lifecycleRole?: string;
|
|
2359
|
+
/**
|
|
2360
|
+
* Intended READER of this resource's generated labels — the register the label
|
|
2361
|
+
* generator should adopt: {@link LabelAudience.END_USER} for consumer surfaces
|
|
2362
|
+
* (todos, lists, profile), {@link LabelAudience.ADMIN} for operator /
|
|
2363
|
+
* back-office resources (users, organizations, billing, roles, audit),
|
|
2364
|
+
* {@link LabelAudience.DEVELOPER} for integration / technical resources (API
|
|
2365
|
+
* keys, webhooks, M2M, SCIM/SIEM). An operation may override it per-operation
|
|
2366
|
+
* via {@link ResourceOperationVariantSpecification.audienceOverride}.
|
|
2367
|
+
*
|
|
2368
|
+
* **Required.** Every resource spec must declare its audience so the label
|
|
2369
|
+
* generator picks the correct register (product copy vs operator console vs
|
|
2370
|
+
* technical / integration voice) without guessing from field names. The
|
|
2371
|
+
* labelling projector still keeps an end-user-normalizing fallback for the
|
|
2372
|
+
* rare hand-built config paths that bypass the authoring factories, but the
|
|
2373
|
+
* type contract now forces authors to make the choice explicitly.
|
|
2374
|
+
*/
|
|
2375
|
+
audience: LabelAudience;
|
|
2376
|
+
/**
|
|
2377
|
+
* The resource's primary scope — **factory-set, never author-set**.
|
|
2378
|
+
*
|
|
2379
|
+
* The specification author declares scope via the fourth `options` argument
|
|
2380
|
+
* to {@link resourceSpecification}; the factory writes that resolved scope
|
|
2381
|
+
* here so downstream consumers, including
|
|
2382
|
+
* {@link resourceSpecificationFromFrontendConfiguration}'s re-validation
|
|
2383
|
+
* passes, can read it from `base.resourcePrimaryScope`.
|
|
2384
|
+
*
|
|
2385
|
+
* Optional only as a soft-fail concession to hand-built spec configs
|
|
2386
|
+
* that bypass both authoring factories — those paths intentionally
|
|
2387
|
+
* forfeit the m2m channel × scope cross-check on the re-validation
|
|
2388
|
+
* seams. Every spec produced by either factory carries this field.
|
|
2389
|
+
*
|
|
2390
|
+
* There is no local drift check between this declared value and the
|
|
2391
|
+
* registry-assembled `resourcePrimaryScope`: this layer cannot observe the
|
|
2392
|
+
* real `ResourceRelationship[]` needed to make that comparison. The
|
|
2393
|
+
* registry/companion assembly layer performs that cross-check when both
|
|
2394
|
+
* signals are available.
|
|
2395
|
+
*/
|
|
2396
|
+
resourcePrimaryScope?: ResourcePrimaryScope;
|
|
2397
|
+
/** Public-import-oriented metadata for downstream code-handling prompts. */
|
|
2398
|
+
codeHandling?: ResourceSpecificationCodeHandling;
|
|
2399
|
+
|
|
2400
|
+
/**
|
|
2401
|
+
* Per-field specification decorators for the resource's `mainSchema`.
|
|
2402
|
+
*
|
|
2403
|
+
* Keys are field names of `TMainSchema`; values are decorated Zod schemas
|
|
2404
|
+
* from the same shape (e.g., `shape.status.enumSpec({ ... })`).
|
|
2405
|
+
*
|
|
2406
|
+
* The merge happens at **module evaluation time** — calling `.enumSpec()`
|
|
2407
|
+
* on a shape field mutates its metadata in place. The `fields` property
|
|
2408
|
+
* exists primarily for type safety (`keyof ObjectShape<TMainSchema>`) and
|
|
2409
|
+
* as a declaration container — same semantics as `ResourceUIBehavior.fields`.
|
|
2410
|
+
*/
|
|
2411
|
+
fields?: {
|
|
2412
|
+
[K in keyof ObjectShape<TSchema>]?: ObjectShape<TSchema>[K];
|
|
2413
|
+
};
|
|
2414
|
+
/**
|
|
2415
|
+
* Explicit field metadata entries that do not live on `mainSchema`.
|
|
2416
|
+
*
|
|
2417
|
+
* Use this for inherited/variant-only fields or any companion-facing field
|
|
2418
|
+
* semantics that should not depend on cross-package schema singleton sharing.
|
|
2419
|
+
*/
|
|
2420
|
+
additionalFieldSpecs?: ExtractedFieldSpec[];
|
|
2421
|
+
|
|
2422
|
+
/** Semantic clarification for operations. */
|
|
2423
|
+
operations?: ResourceOperationSpecificationMap<TCustomOp, TCoreOp>;
|
|
2424
|
+
/** Generated PDF field semantics exposed to companion/spec consumers. */
|
|
2425
|
+
pdfTemplates?: ResourcePdfTemplateSpecification[];
|
|
2426
|
+
/** CSV/JSON export companions derived from LIST/SEARCH `collectionExport` declarations. */
|
|
2427
|
+
collectionExports?: ResourceCollectionExportSpecification[];
|
|
2428
|
+
/** Frontend-facing semantic layer derived from UI behavior leaves. */
|
|
2429
|
+
frontend?: ResourceSpecificationFrontendConfig<TCustomOp, TCoreOp>;
|
|
2430
|
+
/** Domain caveats not encoded structurally elsewhere. */
|
|
2431
|
+
businessConstraints?: string[];
|
|
2432
|
+
};
|
|
2433
|
+
|
|
2434
|
+
export type AnyResourceSpecificationConfig = ResourceSpecificationConfig<any, any, any>;
|
|
2435
|
+
|
|
2436
|
+
/**
|
|
2437
|
+
* Resource specification overlay — keyed by resource type.
|
|
2438
|
+
* Same structural pattern as `ResourceUIBehavior = Record<string, ResourceUIBehaviorConfig>`.
|
|
2439
|
+
*/
|
|
2440
|
+
export type ResourceSpecification = Record<string, AnyResourceSpecificationConfig>;
|
|
2441
|
+
```
|
|
2442
|
+
## Import Origins
|
|
2443
|
+
|
|
2444
|
+
- `@wildo-ai/saas-specifications`
|
|
2445
|
+
|
|
2446
|
+
## Source Excerpts
|
|
2447
|
+
|
|
2448
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
2449
|
+
|
|
2450
|
+
```typescript
|
|
2451
|
+
*
|
|
2452
|
+
* Type-safe factory for authoring a `ResourceSpecificationConfig`.
|
|
2453
|
+
*
|
|
2454
|
+
* Mirrors `resourceUIBehavior()` — the `_factory` parameter is for type
|
|
2455
|
+
* inference only and is never invoked by the spec layer. The schema is
|
|
2456
|
+
* used to resolve `ObjectShape` so that `{primitive}Spec()` decorators
|
|
2457
|
+
* are type-checked against real fields.
|
|
2458
|
+
*
|
|
2459
|
+
* The callback runs immediately at module evaluation time. In the companion
|
|
2460
|
+
* context (where specifications are imported), this attaches `{primitive}Spec`
|
|
2461
|
+
* metadata to the schema's `customFieldMetadata`. In the frontend context
|
|
2462
|
+
* (where specifications are never imported), this code never runs, so no
|
|
2463
|
+
* semantic prose ends up in the browser bundle.
|
|
2464
|
+
*
|
|
2465
|
+
* **Explicit scope declaration.** The fourth `options` argument carries an
|
|
2466
|
+
* explicit `resourcePrimaryScope`. TypeScript enforces its presence at compile
|
|
2467
|
+
* time, so every specification call site declares scope.
|
|
2468
|
+
* That declared value is then:
|
|
2469
|
+
*
|
|
2470
|
+
* 1. Threaded into every `validateResourceOperationsCommunications` call
|
|
2471
|
+
* so the M2M channel × scope cross-check fires end-to-end on
|
|
2472
|
+
* every operation block, including the re-validation paths inside
|
|
2473
|
+
* {@link resourceSpecificationFromFrontendConfiguration}.
|
|
2474
|
+
* 2. Folded into the returned config (`resourcePrimaryScope` field) so
|
|
2475
|
+
* the frontend-config sibling can read it from `base`, preserving scope
|
|
2476
|
+
* context across the base → frontend handoff.
|
|
2477
|
+
*
|
|
2478
|
+
* **No local drift-check.** Calling a resource configuration factory with an
|
|
2479
|
+
* empty relationships array produces its empty-input fallback, not the real
|
|
2480
|
+
* scope for `APPLICATION`, `USER_SELF` or `ANONYMOUS` resources. This layer
|
|
2481
|
+
* therefore lacks the real `ResourceRelationship[]` inputs required for a
|
|
2482
|
+
* meaningful comparison and must not manufacture one.
|
|
2483
|
+
*
|
|
2484
|
+
* The genuine cross-check between this declared scope and the registry-
|
|
2485
|
+
* assembled scope happens at the registry/companion assembly layer, where
|
|
2486
|
+
* both signals coexist.
|
|
2487
|
+
*
|
|
2488
|
+
* @param _factory - The resource configuration factory (function form) or
|
|
2489
|
+
* a pre-built configuration object. Used purely for TypeScript inference
|
|
2490
|
+
* of `TCustomOp` / `TCoreOp` / `TSchema` for most validation. PDF-template
|
|
2491
|
+
* operation validation does materialize this factory with an empty
|
|
2492
|
+
* relationships array to inspect generated regenerate operations; that check
|
|
2493
|
+
* is limited to operation shape and must not be used as a registry-scope
|
|
2494
|
+
* drift signal.
|
|
2495
|
+
* @param schema - The resource's main Zod schema.
|
|
2496
|
+
* @param configFactory - Callback producing the specification content.
|
|
2497
|
+
* @param options - REQUIRED: declares the resource's `resourcePrimaryScope`.
|
|
2498
|
+
* See {@link ResourceSpecificationOptions} for the rationale.
|
|
2499
|
+
*
|
|
2500
|
+
* @example
|
|
2501
|
+
* ```ts
|
|
2502
|
+
* export const todosSpec = resourceSpecification(
|
|
2503
|
+
* todosFactory, TodoSchema,
|
|
2504
|
+
* ({ schemaShape }) => ({
|
|
2505
|
+
* purpose: 'Central entity for task tracking',
|
|
2506
|
+
* businessRole: 'Primary work item',
|
|
2507
|
+
* fields: {
|
|
2508
|
+
* status: schemaShape.status.enumSpec({
|
|
2509
|
+
* meaning: 'Current lifecycle state',
|
|
2510
|
+
* values: { pending: { meaning: 'Created but not started' } },
|
|
2511
|
+
* }),
|
|
2512
|
+
* },
|
|
2513
|
+
* operations: {
|
|
2514
|
+
* create: {
|
|
2515
|
+
* purpose: 'Create a new work item.',
|
|
2516
|
+
* },
|
|
2517
|
+
* },
|
|
2518
|
+
* }),
|
|
2519
|
+
* { resourcePrimaryScope: ResourcePrimaryScope.ORGANIZATIONS },
|
|
2520
|
+
* );
|
|
2521
|
+
* ```
|
|
2522
|
+
*/
|
|
2523
|
+
export function resourceSpecification<
|
|
2524
|
+
TCustomOp extends EnumLikeType | undefined,
|
|
2525
|
+
TCoreOp extends Partial<CoreResourceOperation> | undefined,
|
|
2526
|
+
TSchema extends z.ZodTypeAny,
|
|
2527
|
+
>(
|
|
2528
|
+
_factory: ResourceConfigLike<TCustomOp, TCoreOp, TSchema>,
|
|
2529
|
+
schema: TSchema,
|
|
2530
|
+
configFactory: (
|
|
2531
|
+
params: ResourceSpecificationCallbackParams<TCustomOp, TCoreOp, TSchema>,
|
|
2532
|
+
) => ResourceSpecificationConfig<TCustomOp, TCoreOp, TSchema>,
|
|
2533
|
+
options: ResourceSpecificationOptions,
|
|
2534
|
+
): ResourceSpecificationConfig<TCustomOp, TCoreOp, TSchema> {
|
|
2535
|
+
const schemaShape = (
|
|
2536
|
+
schema && 'shape' in schema
|
|
2537
|
+
? (schema as unknown as z.ZodObject<any>).shape
|
|
2538
|
+
: getZodObjectShape(schema)
|
|
2539
|
+
) as ObjectShape<TSchema>;
|
|
2540
|
+
|
|
2541
|
+
const config = configFactory({ schema, schemaShape });
|
|
2542
|
+
|
|
2543
|
+
// Resolve scope and the runtime config used by the pdfTemplates validator
|
|
2544
|
+
// from whichever signal the spec author supplied. `resourceRelationships`
|
|
2545
|
+
// is the preferred path — it materializes the resource configuration once
|
|
2546
|
+
// with the real registry rels, so scope derives from the same
|
|
2547
|
+
// `isPrimaryScope: true` signal the runtime uses, AND the validator gets
|
|
2548
|
+
// a pre-resolved config (avoiding the failing `_factory([])` call for
|
|
2549
|
+
// resources whose primary scope comes from a parent rel).
|
|
2550
|
+
const { declaredScope, validatorResourceConfig } = resolveScopeAndValidatorConfig(
|
|
2551
|
+
_factory,
|
|
2552
|
+
options,
|
|
2553
|
+
);
|
|
2554
|
+
|
|
2555
|
+
validateResourceOperationsCommunications(
|
|
2556
|
+
'operations.',
|
|
2557
|
+
config.operations as Record<string, ResourceOperationSpecification | undefined> | undefined,
|
|
2558
|
+
declaredScope,
|
|
2559
|
+
);
|
|
2560
|
+
validateResourceOperationsCommunications(
|
|
2561
|
+
'frontend.views.',
|
|
2562
|
+
config.frontend?.views as Record<string, ResourceFrontendViewSpecification | undefined> | undefined,
|
|
2563
|
+
declaredScope,
|
|
2564
|
+
);
|
|
2565
|
+
validateResourceOperationsScheduledExecution(
|
|
2566
|
+
'operations.',
|
|
2567
|
+
config.operations as Record<string, ResourceOperationSpecification | undefined> | undefined,
|
|
2568
|
+
);
|
|
2569
|
+
validateResourceOperationsScheduledExecution(
|
|
2570
|
+
'frontend.views.',
|
|
2571
|
+
config.frontend?.views as Record<string, ResourceFrontendViewSpecification | undefined> | undefined,
|
|
2572
|
+
);
|
|
2573
|
+
validateResourcePdfTemplates('', config.pdfTemplates, schema, validatorResourceConfig);
|
|
2574
|
+
validateResourceCollectionExports('', config.collectionExports, Object.keys(config.operations ?? {}));
|
|
2575
|
+
|
|
2576
|
+
// Fail-closed shape validator for `fields` /
|
|
2577
|
+
// `additionalFieldSpecs`. Runs at module-load time so authors see
|
|
2578
|
+
// structural mistakes (`meaning` blank, `enumDeclaration` missing,
|
|
2579
|
+
// `arraySpec.elementMeaning` blank, ENUM-element array missing
|
|
2580
|
+
// `elementType.enumDeclaration`, etc.) at the call site rather than
|
|
2581
|
+
// inside a downstream rendered prompt. Registry-presence for
|
|
2582
|
+
// `foreignKeySpec` is intentionally NOT checked here — `_core` does
|
|
2583
|
+
// not see `ResourceRelationship[]`; the companion-level completeness
|
|
2584
|
+
// validator owns that cross-check.
|
|
2585
|
+
//
|
|
2586
|
+
// The resource-type hint in the prefix comes from `_factory` (either
|
|
2587
|
+
// the function's `name` stripped of the `_ResourceConfiguration_
|
|
2588
|
+
// InitializationFactory` suffix, or — for rare object-form factories —
|
|
2589
|
+
// the `resourceType` slot directly). Best-effort: when the hint cannot
|
|
2590
|
+
// be derived, the prefix falls back to the bare `resourceSpecification():`
|
|
2591
|
+
// label, matching the pre-hint behaviour.
|
|
2592
|
+
const resourceTypeHint = extractResourceTypeHintFromFactory(_factory);
|
|
2593
|
+
const fieldShapesPrefix = resourceTypeHint.length > 0
|
|
2594
|
+
? `resourceSpecification(${resourceTypeHint}): `
|
|
2595
|
+
: 'resourceSpecification(): ';
|
|
2596
|
+
validateFieldShapes(fieldShapesPrefix, {
|
|
2597
|
+
fields: config.fields as Record<string, z.ZodTypeAny> | undefined,
|
|
2598
|
+
additionalFieldSpecs: config.additionalFieldSpecs,
|
|
2599
|
+
});
|
|
2600
|
+
|
|
2601
|
+
// Attach the resolved scope so the frontend-config sibling
|
|
2602
|
+
// (`resourceSpecificationFromFrontendConfiguration`) can read it from
|
|
2603
|
+
// `base.resourcePrimaryScope` and thread it into its own re-validation
|
|
2604
|
+
// passes without losing base → frontend scope context.
|
|
2605
|
+
return {
|
|
2606
|
+
...config,
|
|
2607
|
+
resourcePrimaryScope: declaredScope,
|
|
2608
|
+
} as ResourceSpecificationConfig<TCustomOp, TCoreOp, TSchema>;
|
|
2609
|
+
}
|
|
2610
|
+
```
|