@wildo-ai/framework-knowledge 1.1.0 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +43 -2
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts +19 -0
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.loader.js +32 -0
- package/dist/esm/framework-knowledge.loader.js.map +1 -1
- package/dist/esm/framework-knowledge.schemas.d.ts +12 -0
- package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.schemas.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +46 -0
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +55 -0
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +4 -4
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +3 -3
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -3
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +22 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +4 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +4 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -13
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +3 -4
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +3 -3
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +54 -0
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +127 -0
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +76 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +92 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +30 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +29 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +9 -44
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +4 -53
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +31 -0
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +26 -0
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -8
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +5 -3
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +4 -5
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +25 -4
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -0
- package/dist/knowledge/manifest.json +8 -8
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +51 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +43 -0
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +8 -7
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +6 -4
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +4 -6
- package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +5 -4
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +4 -6
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +0 -4
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -6
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +49 -22
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +14 -6
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +2 -4
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +46 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +7 -3
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +18 -4
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +4 -2
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +2 -3
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +8 -7
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +3 -5
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +0 -2
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +41 -0
- package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +100 -0
- package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +117 -0
- package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +86 -0
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +61 -0
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +41 -0
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +21 -4
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +14 -57
- package/dist/knowledge/playbooks/top_down.compliance-research/method.md +76 -0
- package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +42 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +3 -5
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +3 -1
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +3 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -5
- package/dist/knowledge/playbooks/top_down.phase-gate/method.md +8 -4
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +9 -7
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +2 -2
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +8 -7
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +0 -2
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +2 -2
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +8 -7
- package/dist/knowledge/references/companion.technical-doc.service.md +102 -2
- package/dist/knowledge/references/example.config.app-shell.full.md +0 -1
- package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
- package/dist/knowledge/references/platform.config.saas.md +1 -0
- package/dist/knowledge/references/presets.models.surface-policy.md +19 -10
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +25 -1
- package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +45 -0
- package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +34 -0
- package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +45 -0
- package/dist/knowledge/references/saas.frontend.public-shell.identity-mode.md +65 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +89 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +31 -4
- package/dist/knowledge/references/saas.models.engine-capabilities.md +26 -6
- package/dist/knowledge/references/saas.models.file-upload-grant.md +179 -0
- package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +124 -0
- package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +99 -0
- package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +127 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +4 -3
- package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +42 -0
- package/dist/knowledge/references/saas.specifications.application-authored-document-fact-specification.contract.md +29 -0
- package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +11 -31
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +32 -2
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +29 -6
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +20 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +22 -0
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +6 -0
- package/dist/knowledge/references/zod.decorators.field-spec-params.md +31 -5
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +43 -0
- package/dist/knowledge/references/zod.decorators.primitive-ui.md +3 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +15 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +3 -2
- package/dist/knowledge/registries/framework-topics.json +99 -1
- package/dist/knowledge/registries/playbooks.json +81 -8
- package/dist/knowledge/registries/source-tags.json +757 -588
- package/dist/knowledge/skills/INDEX.md +3 -3
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +5 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +66 -37
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +40 -7
- package/dist/knowledge/skills/config-app-shell/SKILL.md +25 -1
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +25 -1
- package/dist/knowledge/skills/config-app-shell/references/framework-public-shell-identity-api.md +124 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +23 -1
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +19 -10
- package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md +47 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +75 -2
- package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +98 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +54 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +232 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +149 -0
- package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +114 -0
- package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +133 -0
- package/dist/knowledge/skills/config-saas/SKILL.md +19 -2
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +111 -0
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +30 -9
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +1 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +2 -1
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +4 -3
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +20 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +20 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +20 -0
- package/dist/knowledge/skills/resource-add-field/SKILL.md +3 -3
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +104 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +13 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +71 -4
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +89 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +22 -1
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-file-upload-grant-contract.md +192 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +28 -8
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +15 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +6 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +89 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +43 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +3 -0
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +20 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +31 -5
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +22 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +45 -0
- package/dist/knowledge/topic-index.json +504 -156
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +4 -4
- package/dist/esm/.builder.pid +0 -9
|
@@ -143,6 +143,7 @@ export const WildoSaasConfigSchema = z.strictObject({
|
|
|
143
143
|
* empty ARRAY is the different, positive answer — this surface sets nothing of its own.
|
|
144
144
|
*/
|
|
145
145
|
clientStorage: ApplicationClientStorageInventorySchema.optional(),
|
|
146
|
+
operatingJurisdictions: ApplicationOperatingJurisdictionsSchema.optional(),
|
|
146
147
|
operatorComplianceIdentity: ApplicationOperatorComplianceIdentitySchema.optional(),
|
|
147
148
|
providerComplianceChoices: ApplicationProviderComplianceChoicesSchema.optional(),
|
|
148
149
|
|
|
@@ -73,7 +73,8 @@ File: `backend-api/src/modules/<module>/addons/flows-actors/*.ts`. The system mu
|
|
|
73
73
|
be `kind: ACTOR` with an actor whose `executionMode` is `AGENTIC` and a bound
|
|
74
74
|
`agentRef`. If it renders an in-app chat, it already qualifies — build it via
|
|
75
75
|
`flows-actors-chat-assistant`. Verify what will be advertised:
|
|
76
|
-
|
|
76
|
+
(There is no live introspection query for A2A exposure yet — verify against the agent/flow
|
|
77
|
+
declarations in `shared-lib` themselves.)
|
|
77
78
|
|
|
78
79
|
### Step 2: Enable external auth (OIDC provider + OAuth client)
|
|
79
80
|
External agents get a token from YOUR app's OIDC provider. For **user-delegated**
|
|
@@ -102,9 +102,10 @@ export interface A2A_AgentCard {
|
|
|
102
102
|
|
|
103
103
|
## The A2A task surface (`tasks/get` / `tasks/cancel`)
|
|
104
104
|
|
|
105
|
-
Read this when an external agent needs to start work it will come back for.
|
|
106
|
-
|
|
107
|
-
|
|
105
|
+
Read this when an external agent needs to start work it will come back for. A turn that pauses
|
|
106
|
+
for human approval also becomes a task: it reaches `input-required`, persists the decision it is
|
|
107
|
+
waiting on, and leaves that state once its execution moves on. Both paths into a task are live,
|
|
108
|
+
so an integration you build now can encounter either.
|
|
108
109
|
|
|
109
110
|
The key thing to understand is **when a task exists at all** — most turns never create
|
|
110
111
|
one, and that is deliberate rather than a gap.
|
|
@@ -890,6 +890,9 @@ export interface SpecificationsCompanionExports<
|
|
|
890
890
|
// a partial register is useful and its holes are REPORTED per provider against
|
|
891
891
|
// the application's configured set, rather than blocking anything.
|
|
892
892
|
TProcessorRegister = ApplicationProcessorRegister,
|
|
893
|
+
// Appended STRICTLY LAST: the human half of the document facts, in its own
|
|
894
|
+
// family, because the derived one is REGENERATED whole (#192).
|
|
895
|
+
TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
|
|
893
896
|
> {
|
|
894
897
|
resourceSpecifications: TResourceSpecifications;
|
|
895
898
|
applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
|
|
@@ -1274,6 +1277,23 @@ export interface SpecificationsCompanionExports<
|
|
|
1274
1277
|
* Omitting it is honest: unresolved document facts remain visible gaps.
|
|
1275
1278
|
*/
|
|
1276
1279
|
documentFactSpecification?: TDocumentFactSpecification;
|
|
1280
|
+
/**
|
|
1281
|
+
* Accepted application governed-document facts **only a human may establish** — a creator decision
|
|
1282
|
+
* or a qualified review (`document-facts-authored`).
|
|
1283
|
+
*
|
|
1284
|
+
* The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
|
|
1285
|
+
* rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
|
|
1286
|
+
* run with nothing to notice: there is no compare-and-swap here, deliberately
|
|
1287
|
+
* (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
|
|
1288
|
+
* other's reach.
|
|
1289
|
+
*
|
|
1290
|
+
* No producer may write this family — it has no generation contract, and that absence is the design
|
|
1291
|
+
* rather than an omission.
|
|
1292
|
+
*
|
|
1293
|
+
* A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
|
|
1294
|
+
* is variadic for exactly that reason.
|
|
1295
|
+
*/
|
|
1296
|
+
authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
|
|
1277
1297
|
/**
|
|
1278
1298
|
* WHO else processes this application's personal data — legal identity, processing region and the
|
|
1279
1299
|
* processor's own subprocessors (issue #88).
|
|
@@ -796,6 +796,9 @@ export interface SpecificationsCompanionExports<
|
|
|
796
796
|
// a partial register is useful and its holes are REPORTED per provider against
|
|
797
797
|
// the application's configured set, rather than blocking anything.
|
|
798
798
|
TProcessorRegister = ApplicationProcessorRegister,
|
|
799
|
+
// Appended STRICTLY LAST: the human half of the document facts, in its own
|
|
800
|
+
// family, because the derived one is REGENERATED whole (#192).
|
|
801
|
+
TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
|
|
799
802
|
> {
|
|
800
803
|
resourceSpecifications: TResourceSpecifications;
|
|
801
804
|
applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
|
|
@@ -1180,6 +1183,23 @@ export interface SpecificationsCompanionExports<
|
|
|
1180
1183
|
* Omitting it is honest: unresolved document facts remain visible gaps.
|
|
1181
1184
|
*/
|
|
1182
1185
|
documentFactSpecification?: TDocumentFactSpecification;
|
|
1186
|
+
/**
|
|
1187
|
+
* Accepted application governed-document facts **only a human may establish** — a creator decision
|
|
1188
|
+
* or a qualified review (`document-facts-authored`).
|
|
1189
|
+
*
|
|
1190
|
+
* The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
|
|
1191
|
+
* rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
|
|
1192
|
+
* run with nothing to notice: there is no compare-and-swap here, deliberately
|
|
1193
|
+
* (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
|
|
1194
|
+
* other's reach.
|
|
1195
|
+
*
|
|
1196
|
+
* No producer may write this family — it has no generation contract, and that absence is the design
|
|
1197
|
+
* rather than an omission.
|
|
1198
|
+
*
|
|
1199
|
+
* A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
|
|
1200
|
+
* is variadic for exactly that reason.
|
|
1201
|
+
*/
|
|
1202
|
+
authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
|
|
1183
1203
|
/**
|
|
1184
1204
|
* WHO else processes this application's personal data — legal identity, processing region and the
|
|
1185
1205
|
* processor's own subprocessors (issue #88).
|
|
@@ -212,6 +212,7 @@ export const specificationsCompanionExports: SpecificationsCompanionExports<
|
|
|
212
212
|
* decisions remain private runtime state.
|
|
213
213
|
*/
|
|
214
214
|
documentFactSpecification: applicationDocumentFactSpecification,
|
|
215
|
+
authoredDocumentFactSpecification: applicationAuthoredDocumentFactSpecification,
|
|
215
216
|
/**
|
|
216
217
|
* The accepted typed build plan (`build-plan` family, `BuildPlanTaskGraph`).
|
|
217
218
|
* The bottom-up dispatch playbook's coding owner reads it from the verified
|
package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md
CHANGED
|
@@ -101,6 +101,9 @@ export interface SpecificationsCompanionExports<
|
|
|
101
101
|
// a partial register is useful and its holes are REPORTED per provider against
|
|
102
102
|
// the application's configured set, rather than blocking anything.
|
|
103
103
|
TProcessorRegister = ApplicationProcessorRegister,
|
|
104
|
+
// Appended STRICTLY LAST: the human half of the document facts, in its own
|
|
105
|
+
// family, because the derived one is REGENERATED whole (#192).
|
|
106
|
+
TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
|
|
104
107
|
> {
|
|
105
108
|
resourceSpecifications: TResourceSpecifications;
|
|
106
109
|
applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
|
|
@@ -485,6 +488,23 @@ export interface SpecificationsCompanionExports<
|
|
|
485
488
|
* Omitting it is honest: unresolved document facts remain visible gaps.
|
|
486
489
|
*/
|
|
487
490
|
documentFactSpecification?: TDocumentFactSpecification;
|
|
491
|
+
/**
|
|
492
|
+
* Accepted application governed-document facts **only a human may establish** — a creator decision
|
|
493
|
+
* or a qualified review (`document-facts-authored`).
|
|
494
|
+
*
|
|
495
|
+
* The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
|
|
496
|
+
* rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
|
|
497
|
+
* run with nothing to notice: there is no compare-and-swap here, deliberately
|
|
498
|
+
* (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
|
|
499
|
+
* other's reach.
|
|
500
|
+
*
|
|
501
|
+
* No producer may write this family — it has no generation contract, and that absence is the design
|
|
502
|
+
* rather than an omission.
|
|
503
|
+
*
|
|
504
|
+
* A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
|
|
505
|
+
* is variadic for exactly that reason.
|
|
506
|
+
*/
|
|
507
|
+
authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
|
|
488
508
|
/**
|
|
489
509
|
* WHO else processes this application's personal data — legal identity, processing region and the
|
|
490
510
|
* processor's own subprocessors (issue #88).
|
|
@@ -38,7 +38,7 @@ Locate the surfaces that may need editing using these app-relative globs:
|
|
|
38
38
|
| Frontend UI behavior | `frontend/src/modules/*/resources/*/*.ui-behavior.tsx` |
|
|
39
39
|
| Specification | `specifications/src/modules/*/resources/*.resource.specification.ts` |
|
|
40
40
|
| Backend (rare) | `backend-api/src/modules/*/resources/*/*.resource-handlers.ts` |
|
|
41
|
-
| i18n labels | `frontend/src/i18n/**/*.json` (
|
|
41
|
+
| i18n labels | `frontend/src/i18n/**/*.json` (list the keys currently needed: `wildo context info frontend-labels-needed-info`) |
|
|
42
42
|
|
|
43
43
|
If the project diverges from this layout, find the resource by grepping
|
|
44
44
|
for the `R.<RESOURCE>` enum value or for the existing field's
|
|
@@ -172,8 +172,8 @@ Minimum label impact:
|
|
|
172
172
|
- `<resource>.<fieldName>.label`
|
|
173
173
|
- `<resource>.<fieldName>.<enumValue>` for each enum value
|
|
174
174
|
|
|
175
|
-
Use the existing project placement pattern
|
|
176
|
-
|
|
175
|
+
Use the existing project placement pattern; `wildo context info frontend-labels-needed-info`
|
|
176
|
+
lists the label keys the frontend currently needs, with their placement metadata.
|
|
177
177
|
|
|
178
178
|
### Re-run Translation When Text Changes
|
|
179
179
|
|
package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md
CHANGED
|
@@ -41,6 +41,21 @@ export interface ForeignKeyStructuralParams {
|
|
|
41
41
|
* (e.g. `referrerScopeType`). Without it, `polymorphicVariants` is rename-only.
|
|
42
42
|
*/
|
|
43
43
|
polymorphicDiscriminatorField?: string;
|
|
44
|
+
/**
|
|
45
|
+
* EXPLICIT target resource type, for an FK whose FIELD NAME cannot resolve it.
|
|
46
|
+
*
|
|
47
|
+
* The frontend resolves a reference field's target through the field-name → resource map
|
|
48
|
+
* (enriched from relationships' `foreignKeyField`). That works only when the field is named for
|
|
49
|
+
* its target (`assignedToUserId`) or a relationship declares it — and relationship FK names are
|
|
50
|
+
* held to the `Id`/`Ids` convention. A field that references a resource under its OWN vocabulary
|
|
51
|
+
* (`icpRefs` inside a specification document, a rename-only FK) has no honest entry in that map;
|
|
52
|
+
* declaring the target here lets the reference display resolve, label and navigate it without
|
|
53
|
+
* bending the field's name or the map's uniqueness.
|
|
54
|
+
*
|
|
55
|
+
* Takes precedence over the field-name map; polymorphic variants (above) still win over both,
|
|
56
|
+
* because a per-record discriminator is more specific than any static declaration.
|
|
57
|
+
*/
|
|
58
|
+
referencedResourceType?: string;
|
|
44
59
|
}
|
|
45
60
|
```
|
|
46
61
|
|
|
@@ -685,6 +700,26 @@ export const CardActionPlacementSchema = z.object({
|
|
|
685
700
|
/** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
|
|
686
701
|
export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
|
|
687
702
|
|
|
703
|
+
/**
|
|
704
|
+
* Who paints the identity GLYPH on this operation's page header.
|
|
705
|
+
*
|
|
706
|
+
* The header band renders the resource's registry icon beside the identity line by default. A
|
|
707
|
+
* `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
|
|
708
|
+
* per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
|
|
709
|
+
*
|
|
710
|
+
* Declared at the OPERATION layer rather than detected from the template, deliberately: the
|
|
711
|
+
* resource icon renders before the template mounts, so detection could only suppress it after the
|
|
712
|
+
* fact — a glyph that flashes and vanishes on every load. Mirrors
|
|
713
|
+
* `SummaryTitlePlacement.TEMPLATE_OWNED`, the same contract one surface over: ceding a
|
|
714
|
+
* framework-owned element to the template is a declaration, not an inference.
|
|
715
|
+
*/
|
|
716
|
+
export enum HeaderIconPlacement {
|
|
717
|
+
/** The framework renders the resource's registry icon (default). */
|
|
718
|
+
AUTO = 'auto',
|
|
719
|
+
/** The header template owns the glyph; the framework renders none. */
|
|
720
|
+
TEMPLATE_OWNED = 'template_owned',
|
|
721
|
+
}
|
|
722
|
+
|
|
688
723
|
export const ResourceOperationFrontendConfigSchema = z.object({
|
|
689
724
|
/**
|
|
690
725
|
* The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
|
|
@@ -696,6 +731,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
696
731
|
* Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
|
|
697
732
|
*/
|
|
698
733
|
surface: z.enum(ResourceOperationFrontendSurface),
|
|
734
|
+
/** Who paints the page header's identity glyph — see {@link HeaderIconPlacement}. Omitted = AUTO. */
|
|
735
|
+
headerIconPlacement: z.enum(HeaderIconPlacement).optional(),
|
|
699
736
|
/**
|
|
700
737
|
* How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
|
|
701
738
|
* (the common case) behaves as `ALWAYS`.
|
|
@@ -775,6 +812,30 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
775
812
|
* without a date heading rather than being dropped.
|
|
776
813
|
*/
|
|
777
814
|
temporalGroupField: z.string().optional(),
|
|
815
|
+
/**
|
|
816
|
+
* Group CARDS-mode rows into buckets by this ENUM field, rendering the
|
|
817
|
+
* enum value's own label as a heading between groups.
|
|
818
|
+
*
|
|
819
|
+
* Sibling of {@link temporalGroupField}, and deliberately NOT the same
|
|
820
|
+
* algorithm. Temporal grouping ADJACENT-MERGES in server order, because
|
|
821
|
+
* dates are open-ended and a page can legitimately revisit one. An enum is
|
|
822
|
+
* a CLOSED, ORDERED vocabulary, so its buckets are emitted in the enum's
|
|
823
|
+
* DECLARATION ORDER regardless of the order rows arrived in — the
|
|
824
|
+
* declaration is the authority for "which concern comes first", and a
|
|
825
|
+
* server sort cannot express it without a second, drifting copy of that
|
|
826
|
+
* order. Rows are therefore collected across the whole fetched page rather
|
|
827
|
+
* than merged adjacently, and no sort needs pairing with it.
|
|
828
|
+
*
|
|
829
|
+
* Headings resolve through `tResourceFieldEnumValue` — the SAME source the
|
|
830
|
+
* filters panel and the promoted quick-filter tabs use, so a bucket
|
|
831
|
+
* heading and its tab can never disagree.
|
|
832
|
+
*
|
|
833
|
+
* Ignored in TABLE mode (column sorting owns the ordering there). Rows
|
|
834
|
+
* whose value is absent, or outside the vocabulary, render in a trailing
|
|
835
|
+
* bucket with no heading rather than being dropped — the same fail-open
|
|
836
|
+
* the temporal grouping makes.
|
|
837
|
+
*/
|
|
838
|
+
enumGroupField: z.string().optional(),
|
|
778
839
|
/**
|
|
779
840
|
* CARDS-mode arrangement — a single-column bordered LIST (default) or an
|
|
780
841
|
* N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
|
|
@@ -828,6 +889,49 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
828
889
|
* into a description via the `.describe()` decorator.
|
|
829
890
|
*/
|
|
830
891
|
hasDescription: z.boolean().optional(),
|
|
892
|
+
/**
|
|
893
|
+
* What happens to an ADJACENT zone (secondary / companion) this operation
|
|
894
|
+
* splits into, once that zone's last content is dismissed — overriding the
|
|
895
|
+
* zone's own `onEmpty` while this operation occupies primary.
|
|
896
|
+
*
|
|
897
|
+
* The zone-level `ZoneConfig.onEmpty` is one value for every destination that
|
|
898
|
+
* splits into that zone, and destinations legitimately disagree: a LIST wants
|
|
899
|
+
* the detail pane to stay put (`EMPTY_STATE`) so the layout does not reflow
|
|
900
|
+
* while a reviewer steps through rows, while a CANVAS wants its width back
|
|
901
|
+
* (`COLLAPSE`) the moment nothing is selected. Both share one secondary zone,
|
|
902
|
+
* so without this override one of them is always wrong.
|
|
903
|
+
*
|
|
904
|
+
* Declared on the SOURCE operation — the one occupying primary — not on the
|
|
905
|
+
* operation that lands in the pane: it answers "what should MY layout do when
|
|
906
|
+
* the detail closes", which is a property of the surface being returned to.
|
|
907
|
+
*
|
|
908
|
+
* Omitted (the common case) defers to the zone, which itself defaults to
|
|
909
|
+
* `ZoneEmptyBehavior.COLLAPSE`. Resolution order is destination → zone →
|
|
910
|
+
* COLLAPSE; see `resolveZoneEmptyBehavior`.
|
|
911
|
+
*/
|
|
912
|
+
adjacentZoneOnEmpty: z.enum(ZoneEmptyBehavior).optional(),
|
|
913
|
+
/**
|
|
914
|
+
* How wide this destination's content may grow in the zone, in the framework's shared width
|
|
915
|
+
* vocabulary — the SAME `ResponsiveMaxWidth` a Surface, a `DisplayLayout` and a `FormLayout` use.
|
|
916
|
+
*
|
|
917
|
+
* Omitted (the common case) is `'content'`: capped and centred at `var(--content-max-width, 80rem)`,
|
|
918
|
+
* right for a form, a list or a detail page and wrong only for content whose value IS the space it
|
|
919
|
+
* occupies — a board, a wide table, a canvas — which declare `'none'`.
|
|
920
|
+
*/
|
|
921
|
+
zoneContentMaxWidth: z.enum(RESPONSIVE_MAX_WIDTH_VALUES).optional(),
|
|
922
|
+
/**
|
|
923
|
+
* Whether this destination's content fills the zone's HEIGHT as well.
|
|
924
|
+
*
|
|
925
|
+
* `true` makes the zone's content boundary a definite-height flex column, so this view's root may use
|
|
926
|
+
* `flex-1 min-h-0` and resolve against something real. Without it a canvas has no intrinsic height
|
|
927
|
+
* and collapses to zero — which is why one had to hand-roll `h-[70vh]`, sizing against the WINDOW
|
|
928
|
+
* rather than the container it sits in. PRIMARY only: an adjacent zone scrolls, so a filling child
|
|
929
|
+
* and a scrolling parent contradict each other.
|
|
930
|
+
*
|
|
931
|
+
* Separate from the width above ON PURPOSE — see `zone-content-geometry.ts` for why the enum that
|
|
932
|
+
* fused them could not express a capped width with a definite height.
|
|
933
|
+
*/
|
|
934
|
+
zoneContentFillsHeight: z.boolean().optional(),
|
|
831
935
|
});
|
|
832
936
|
|
|
833
937
|
/**
|
|
@@ -102,6 +102,17 @@ sending its email, or send an email without a usable token. Delivery is
|
|
|
102
102
|
best-effort—author an explicit product recovery operation such as RESEND when a
|
|
103
103
|
missing email must be recoverable.
|
|
104
104
|
|
|
105
|
+
For a variant whose synchronous round trip legitimately outlives the frontend's
|
|
106
|
+
30-second HTTP default — an operation that calls a model and waits, a blocking
|
|
107
|
+
generation, a long import — declare `clientRequestTimeoutMs` on that variant.
|
|
108
|
+
The frontend applies it as the per-request timeout on every dispatch shape.
|
|
109
|
+
Without it the request is aborted client-side while the server work succeeds:
|
|
110
|
+
the caller renders a network error and the operation-success refresh chain never
|
|
111
|
+
fires, so lists keep showing the pre-operation world. Do not hard-code timeouts
|
|
112
|
+
in consumer hooks instead — the variant is where the operation's own knowledge
|
|
113
|
+
of its duration belongs. Contract and a worked example:
|
|
114
|
+
`references/framework-saas-models-resource-config-api.md`.
|
|
115
|
+
|
|
105
116
|
### Step 5: Align with UI and spec
|
|
106
117
|
|
|
107
118
|
After config changes, `resource-ui-behavior` may need operation view updates;
|
|
@@ -302,6 +313,7 @@ fields (derived from the schema, never caller-supplied). Distinct from `isSystem
|
|
|
302
313
|
- [ ] Operations referenced from `*.ui-behavior.tsx` exist in `*.resources-config.ts`
|
|
303
314
|
- [ ] Variants and discriminator wiring stays consistent with `createSchemaFamily` usage on the schema
|
|
304
315
|
- [ ] Role constraints (`roles: [...]`) match the product intent for each variant
|
|
316
|
+
- [ ] Any variant whose synchronous work can outlive ~30s declares `clientRequestTimeoutMs` (catch with the timeout grep below)
|
|
305
317
|
- [ ] `accessScopeStrategy` is set on every `REFERENCE` relationship (no implicit defaults relied upon)
|
|
306
318
|
- [ ] `contextPolicy` overrides for `LIST`/`SEARCH` are explicit when the relationship is high-cardinality
|
|
307
319
|
- [ ] Every relational `searchableFields` entry uses a `localField` that exists on this schema (and a `relatedJoinField` that exists on the related resource — defaults to `_id`)
|
|
@@ -319,6 +331,7 @@ Run from the app root and substitute the resource / FK field name:
|
|
|
319
331
|
| Relationship is co-located in the module-level relationships file (not inside config) | `rg -n "createResourcesRelationship" shared-lib/src/modules/*/resources/<resource>/<resource>.resources-config.ts` |
|
|
320
332
|
| Custom operation IDs in the UI exist in the resource config | `rg -n "operationLike:\\s*<Resource>_Operations\\." frontend/src/modules/*/resources/<resource>/<resource>.ui-behavior.tsx` |
|
|
321
333
|
| Same custom operation IDs are defined in the resource config | `rg -n "<Resource>_Operations\\." shared-lib/src/modules/*/resources/<resource>/<resource>.resources-config.ts` |
|
|
334
|
+
| Long-running variants declare their client timeout | `rg -n "clientRequestTimeoutMs" shared-lib/src/modules/*/resources/<resource>/<resource>.resources-config.ts` (expect a hit for any variant that generates/imports synchronously) |
|
|
322
335
|
| The two custom-operation lists agree | `comm -23 <(rg -oN "<Resource>_Operations\\.[A-Z_]+" frontend/src/modules/*/resources/<resource>/*.tsx \\| sort -u) <(rg -oN "<Resource>_Operations\\.[A-Z_]+" shared-lib/src/modules/*/resources/<resource>/*.ts \\| sort -u)` |
|
|
323
336
|
|
|
324
337
|
The third grep MUST return zero matches — relationship declarations in
|
|
@@ -202,6 +202,28 @@ export enum IntrospectionTenancyStance {
|
|
|
202
202
|
*/
|
|
203
203
|
APPLICATION_STRUCTURE = 'application-structure',
|
|
204
204
|
|
|
205
|
+
/**
|
|
206
|
+
* The rows are the DEVELOPMENT COMPANION'S OWN RUNTIME PROJECTIONS for the one application it
|
|
207
|
+
* serves — the playbook eligibility board, the build plan, the run write-register, the execution
|
|
208
|
+
* traces. Like `APPLICATION_STRUCTURE` they carry no tenant dimension and no scope predicate can
|
|
209
|
+
* apply; UNLIKE it, they are not derived from the application's source, and the tenancy stance is
|
|
210
|
+
* where that difference must stay visible (added 2026-09-01, creation-board resources plan):
|
|
211
|
+
*
|
|
212
|
+
* - `APPLICATION_STRUCTURE`'s public-read posture (`APP_PUBLIC` variants on the workbench's
|
|
213
|
+
* structural projections) rests on the rows being the application's OWN source, which anyone
|
|
214
|
+
* with the working tree can already read. That argument does NOT extend to runtime state, so a
|
|
215
|
+
* resource declaring this stance is expected to gate its variants on an authenticated role —
|
|
216
|
+
* never `APP_PUBLIC`.
|
|
217
|
+
* - Row-level tenant-anchor checks are bypassed for this stance exactly as for
|
|
218
|
+
* `APPLICATION_STRUCTURE` (the rows carry no anchor BY CONTRACT); authorization comes from the
|
|
219
|
+
* session and the operation's role gate.
|
|
220
|
+
*
|
|
221
|
+
* Fusing this into `APPLICATION_STRUCTURE` was rejected for the enum's own founding reason: an
|
|
222
|
+
* unstated distinction is indistinguishable from an overlooked one, and the next decision site
|
|
223
|
+
* keyed off the stance would inherit a claim nobody checked.
|
|
224
|
+
*/
|
|
225
|
+
APPLICATION_RUNTIME = 'application-runtime',
|
|
226
|
+
|
|
205
227
|
/**
|
|
206
228
|
* The rows carry a tenant dimension and a scope predicate must be pushed into the source.
|
|
207
229
|
*
|
|
@@ -298,10 +320,15 @@ export enum PersistenceAdapter {
|
|
|
298
320
|
* "how rows are reached", and the mechanism behind it is a binding an author declares.
|
|
299
321
|
*
|
|
300
322
|
* Distinct from `HTTP_API`, deliberately, and not merely because the transport differs. Retrieval
|
|
301
|
-
* is
|
|
302
|
-
*
|
|
303
|
-
*
|
|
304
|
-
*
|
|
323
|
+
* is the COMPANION's decision per behavior (amended 2026-09-01): the app-import behaviors run a
|
|
324
|
+
* SUBPROCESS that imports the target application's built modules — seconds per read, requiring
|
|
325
|
+
* that application's `dist`, failing as a thrown behavior — while the creation-plane behaviors
|
|
326
|
+
* are IN-PROCESS projections of the companion's own runtime services (playbook eligibility,
|
|
327
|
+
* build plan, write register, traces). Both reach the engine through the same
|
|
328
|
+
* `IntrospectionResourceSourceBackendPort`; the adapter never encodes the mechanism, which is
|
|
329
|
+
* exactly why a behavior id is an engine-opaque string. Collapsing this into `HTTP_API` would
|
|
330
|
+
* still be wrong for the original reason: its failure mode is a source throwing rather than a
|
|
331
|
+
* row being absent, and nothing here is reached over a network API.
|
|
305
332
|
*
|
|
306
333
|
* ## What every adapter decision site must honor
|
|
307
334
|
*
|
|
@@ -1125,6 +1152,46 @@ export type ResourceConfiguration_Operation_ApiCall<
|
|
|
1125
1152
|
|
|
1126
1153
|
### Origin Package: `@wildo-ai/saas-models`
|
|
1127
1154
|
|
|
1155
|
+
```typescript
|
|
1156
|
+
*
|
|
1157
|
+
* Frontend HTTP timeout for THIS variant, in milliseconds — declare it on any operation whose
|
|
1158
|
+
* synchronous round trip legitimately outlives the frontend client's 30-second default (an
|
|
1159
|
+
* operation that calls a model and waits for the answer, a long import, a blocking generation).
|
|
1160
|
+
*
|
|
1161
|
+
* The frontend resources client applies it as the per-request timeout on every dispatch shape
|
|
1162
|
+
* (api-call, api-call-with-callback, search). An explicit caller-supplied
|
|
1163
|
+
* `RequestOptions.timeout` still wins; omitting the field keeps the client default.
|
|
1164
|
+
*
|
|
1165
|
+
* Why it matters: without it, a long-running operation's request is aborted CLIENT-side while
|
|
1166
|
+
* the server work succeeds — the caller renders a network error, and the operation-success
|
|
1167
|
+
* refresh chain never fires, so lists keep showing the pre-operation world. Declare the
|
|
1168
|
+
* expectation on the variant (the operation knows it is long-running); do not hard-code
|
|
1169
|
+
* timeouts in consumer hooks, which duplicates that knowledge at every call site.
|
|
1170
|
+
*
|
|
1171
|
+
* This is a TRANSPORT expectation only — not a UI/observability signal (that is `riskLevel`)
|
|
1172
|
+
* and not a server-side bound: the backend is free to answer sooner or be cut off by its own
|
|
1173
|
+
* limits.
|
|
1174
|
+
*
|
|
1175
|
+
* @example a custom operation that generates a document before answering
|
|
1176
|
+
* variants: [{
|
|
1177
|
+
* variantType: ResourceOperationVariantType.API_CALL,
|
|
1178
|
+
* roles: [CORE_ORG_ROLES.ORG_MEMBER],
|
|
1179
|
+
* riskLevel: ResourceOperationRiskLevel.MEDIUM,
|
|
1180
|
+
* clientRequestTimeoutMs: 300_000, // five minutes — the generation is synchronous
|
|
1181
|
+
* requestDto: GenerateReportRequest_Schema,
|
|
1182
|
+
* customResponseDto: GenerateReportOutcome_Schema,
|
|
1183
|
+
* }]
|
|
1184
|
+
*/
|
|
1185
|
+
clientRequestTimeoutMs?: number;
|
|
1186
|
+
```
|
|
1187
|
+
## Import Origins
|
|
1188
|
+
|
|
1189
|
+
- `@wildo-ai/saas-models`
|
|
1190
|
+
|
|
1191
|
+
## Source Excerpts
|
|
1192
|
+
|
|
1193
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
1194
|
+
|
|
1128
1195
|
```typescript
|
|
1129
1196
|
*
|
|
1130
1197
|
* Variant builder type that distributes operation-specific fields based on the operation key.
|
|
@@ -383,6 +383,26 @@ export const CardActionPlacementSchema = z.object({
|
|
|
383
383
|
/** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
|
|
384
384
|
export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
|
|
385
385
|
|
|
386
|
+
/**
|
|
387
|
+
* Who paints the identity GLYPH on this operation's page header.
|
|
388
|
+
*
|
|
389
|
+
* The header band renders the resource's registry icon beside the identity line by default. A
|
|
390
|
+
* `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
|
|
391
|
+
* per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
|
|
392
|
+
*
|
|
393
|
+
* Declared at the OPERATION layer rather than detected from the template, deliberately: the
|
|
394
|
+
* resource icon renders before the template mounts, so detection could only suppress it after the
|
|
395
|
+
* fact — a glyph that flashes and vanishes on every load. Mirrors
|
|
396
|
+
* `SummaryTitlePlacement.TEMPLATE_OWNED`, the same contract one surface over: ceding a
|
|
397
|
+
* framework-owned element to the template is a declaration, not an inference.
|
|
398
|
+
*/
|
|
399
|
+
export enum HeaderIconPlacement {
|
|
400
|
+
/** The framework renders the resource's registry icon (default). */
|
|
401
|
+
AUTO = 'auto',
|
|
402
|
+
/** The header template owns the glyph; the framework renders none. */
|
|
403
|
+
TEMPLATE_OWNED = 'template_owned',
|
|
404
|
+
}
|
|
405
|
+
|
|
386
406
|
export const ResourceOperationFrontendConfigSchema = z.object({
|
|
387
407
|
/**
|
|
388
408
|
* The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
|
|
@@ -394,6 +414,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
394
414
|
* Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
|
|
395
415
|
*/
|
|
396
416
|
surface: z.enum(ResourceOperationFrontendSurface),
|
|
417
|
+
/** Who paints the page header's identity glyph — see {@link HeaderIconPlacement}. Omitted = AUTO. */
|
|
418
|
+
headerIconPlacement: z.enum(HeaderIconPlacement).optional(),
|
|
397
419
|
/**
|
|
398
420
|
* How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
|
|
399
421
|
* (the common case) behaves as `ALWAYS`.
|
|
@@ -473,6 +495,30 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
473
495
|
* without a date heading rather than being dropped.
|
|
474
496
|
*/
|
|
475
497
|
temporalGroupField: z.string().optional(),
|
|
498
|
+
/**
|
|
499
|
+
* Group CARDS-mode rows into buckets by this ENUM field, rendering the
|
|
500
|
+
* enum value's own label as a heading between groups.
|
|
501
|
+
*
|
|
502
|
+
* Sibling of {@link temporalGroupField}, and deliberately NOT the same
|
|
503
|
+
* algorithm. Temporal grouping ADJACENT-MERGES in server order, because
|
|
504
|
+
* dates are open-ended and a page can legitimately revisit one. An enum is
|
|
505
|
+
* a CLOSED, ORDERED vocabulary, so its buckets are emitted in the enum's
|
|
506
|
+
* DECLARATION ORDER regardless of the order rows arrived in — the
|
|
507
|
+
* declaration is the authority for "which concern comes first", and a
|
|
508
|
+
* server sort cannot express it without a second, drifting copy of that
|
|
509
|
+
* order. Rows are therefore collected across the whole fetched page rather
|
|
510
|
+
* than merged adjacently, and no sort needs pairing with it.
|
|
511
|
+
*
|
|
512
|
+
* Headings resolve through `tResourceFieldEnumValue` — the SAME source the
|
|
513
|
+
* filters panel and the promoted quick-filter tabs use, so a bucket
|
|
514
|
+
* heading and its tab can never disagree.
|
|
515
|
+
*
|
|
516
|
+
* Ignored in TABLE mode (column sorting owns the ordering there). Rows
|
|
517
|
+
* whose value is absent, or outside the vocabulary, render in a trailing
|
|
518
|
+
* bucket with no heading rather than being dropped — the same fail-open
|
|
519
|
+
* the temporal grouping makes.
|
|
520
|
+
*/
|
|
521
|
+
enumGroupField: z.string().optional(),
|
|
476
522
|
/**
|
|
477
523
|
* CARDS-mode arrangement — a single-column bordered LIST (default) or an
|
|
478
524
|
* N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
|
|
@@ -526,6 +572,49 @@ export const ResourceOperationFrontendConfigSchema = z.object({
|
|
|
526
572
|
* into a description via the `.describe()` decorator.
|
|
527
573
|
*/
|
|
528
574
|
hasDescription: z.boolean().optional(),
|
|
575
|
+
/**
|
|
576
|
+
* What happens to an ADJACENT zone (secondary / companion) this operation
|
|
577
|
+
* splits into, once that zone's last content is dismissed — overriding the
|
|
578
|
+
* zone's own `onEmpty` while this operation occupies primary.
|
|
579
|
+
*
|
|
580
|
+
* The zone-level `ZoneConfig.onEmpty` is one value for every destination that
|
|
581
|
+
* splits into that zone, and destinations legitimately disagree: a LIST wants
|
|
582
|
+
* the detail pane to stay put (`EMPTY_STATE`) so the layout does not reflow
|
|
583
|
+
* while a reviewer steps through rows, while a CANVAS wants its width back
|
|
584
|
+
* (`COLLAPSE`) the moment nothing is selected. Both share one secondary zone,
|
|
585
|
+
* so without this override one of them is always wrong.
|
|
586
|
+
*
|
|
587
|
+
* Declared on the SOURCE operation — the one occupying primary — not on the
|
|
588
|
+
* operation that lands in the pane: it answers "what should MY layout do when
|
|
589
|
+
* the detail closes", which is a property of the surface being returned to.
|
|
590
|
+
*
|
|
591
|
+
* Omitted (the common case) defers to the zone, which itself defaults to
|
|
592
|
+
* `ZoneEmptyBehavior.COLLAPSE`. Resolution order is destination → zone →
|
|
593
|
+
* COLLAPSE; see `resolveZoneEmptyBehavior`.
|
|
594
|
+
*/
|
|
595
|
+
adjacentZoneOnEmpty: z.enum(ZoneEmptyBehavior).optional(),
|
|
596
|
+
/**
|
|
597
|
+
* How wide this destination's content may grow in the zone, in the framework's shared width
|
|
598
|
+
* vocabulary — the SAME `ResponsiveMaxWidth` a Surface, a `DisplayLayout` and a `FormLayout` use.
|
|
599
|
+
*
|
|
600
|
+
* Omitted (the common case) is `'content'`: capped and centred at `var(--content-max-width, 80rem)`,
|
|
601
|
+
* right for a form, a list or a detail page and wrong only for content whose value IS the space it
|
|
602
|
+
* occupies — a board, a wide table, a canvas — which declare `'none'`.
|
|
603
|
+
*/
|
|
604
|
+
zoneContentMaxWidth: z.enum(RESPONSIVE_MAX_WIDTH_VALUES).optional(),
|
|
605
|
+
/**
|
|
606
|
+
* Whether this destination's content fills the zone's HEIGHT as well.
|
|
607
|
+
*
|
|
608
|
+
* `true` makes the zone's content boundary a definite-height flex column, so this view's root may use
|
|
609
|
+
* `flex-1 min-h-0` and resolve against something real. Without it a canvas has no intrinsic height
|
|
610
|
+
* and collapses to zero — which is why one had to hand-roll `h-[70vh]`, sizing against the WINDOW
|
|
611
|
+
* rather than the container it sits in. PRIMARY only: an adjacent zone scrolls, so a filling child
|
|
612
|
+
* and a scrolling parent contradict each other.
|
|
613
|
+
*
|
|
614
|
+
* Separate from the width above ON PURPOSE — see `zone-content-geometry.ts` for why the enum that
|
|
615
|
+
* fused them could not express a capped width with a definite height.
|
|
616
|
+
*/
|
|
617
|
+
zoneContentFillsHeight: z.boolean().optional(),
|
|
529
618
|
});
|
|
530
619
|
|
|
531
620
|
/**
|
|
@@ -72,7 +72,9 @@ File: `shared-lib/src/modules/<module>/resources/<resource>/*.resources-config.t
|
|
|
72
72
|
`ORGANIZATION`- and `APPLICATION`-scoped resources are exposable — a machine token carries no
|
|
73
73
|
`userId`, so USER_SELF / ANONYMOUS operations are unreachable and are never advertised even if
|
|
74
74
|
you set `mcp.exposed`. Confirm the resource's `resourcePrimaryScope` before proceeding.
|
|
75
|
-
|
|
75
|
+
Live resource inventory: `wildo context info resources-registry`. Confirm `resourcePrimaryScope`
|
|
76
|
+
in the resource's own configuration under `shared-lib/` — the registry snapshot lists the
|
|
77
|
+
resources; the scope declaration lives in the config.
|
|
76
78
|
|
|
77
79
|
### Step 2: Choose which operations to expose (and classify instance vs collection)
|
|
78
80
|
Only **DEFAULT, non-bulk, URL-bearing** operations become tools (the standard `API_CALL`
|
|
@@ -90,6 +92,14 @@ tool description falls back to the resource specification's `purpose` / `whenToU
|
|
|
90
92
|
synthesized default — so either author it here or keep the spec prose agent-ready (and
|
|
91
93
|
reconciled: see `spec-resource-update`).
|
|
92
94
|
|
|
95
|
+
**File fields need nothing extra — but know what the agent sees.** An MCP tool call cannot carry
|
|
96
|
+
bytes, so a `z_file()` field advertises a `fileId` the agent has no way to invent. For every exposed
|
|
97
|
+
CREATE / UPDATE with a user-uploadable file field the engine ALSO advertises a derived tool,
|
|
98
|
+
`<resource>__<operation>.upload_grant.<field>`, that mints a single-use upload link, and it appends to
|
|
99
|
+
your operation's description where each field's id comes from. Do not describe the upload in your own
|
|
100
|
+
`description` — the engine's note is derived from the field and stays in step with it. See
|
|
101
|
+
`references/framework-file-upload-grant-contract.md`.
|
|
102
|
+
|
|
93
103
|
### Step 3b (OPTIONAL): Split the catalog across NAMED servers
|
|
94
104
|
One `/mcp` serves ONE flat tool list, so when different consumers need different capability
|
|
95
105
|
postures — a read-only support surface vs a destructive operations one — declare **named servers**
|
|
@@ -212,6 +222,9 @@ curl -X POST https://your-app.example.com/api/v1/mcp \
|
|
|
212
222
|
|
|
213
223
|
- `references/framework-resource-mcp-exposure-contract.md` — source-backed: the `mcp`
|
|
214
224
|
operation-config field (the opt-in contract, description fallback, scope constraints).
|
|
225
|
+
- `references/framework-file-upload-grant-contract.md` — source-backed: what the derived
|
|
226
|
+
`…upload_grant.<field>` tool returns and how an agent turns it into a `fileId`. Read when an exposed
|
|
227
|
+
CREATE / UPDATE carries a `z_file()` field.
|
|
215
228
|
- `references/framework-named-mcp-servers-contract.md` — source-backed: declaring NAMED MCP
|
|
216
229
|
servers (`resourceServerInstances`) when one catalog is not enough, and how per-server
|
|
217
230
|
audiences make the split a real boundary. Read only if you need more than one MCP surface.
|
|
@@ -250,6 +263,10 @@ curl -X POST https://your-app.example.com/api/v1/mcp \
|
|
|
250
263
|
Without it, the test passes identically when the whole resource was never exposed, and would keep
|
|
251
264
|
passing if the withdrawal logic were deleted. Grep your own tests:
|
|
252
265
|
`rg -n "not\.toContain\('.*__" ` — each hit needs a `toContain` for the same resource nearby.
|
|
266
|
+
- [ ] IF an exposed CREATE / UPDATE carries a `z_file()` field: `tools/list` shows the derived
|
|
267
|
+
`…upload_grant.<field>` tool beside it, and the parent's description ends with a `File fields:` note.
|
|
268
|
+
Grep the live catalogue: `rg "upload_grant\." <tools-list.json>` — one hit per uploadable field of
|
|
269
|
+
each exposed CREATE / UPDATE, none for a generated (PDF-template) field.
|
|
253
270
|
- [ ] No operation carrying an `unimplementedAcknowledgement` is relied on as a tool. You do NOT
|
|
254
271
|
need to retract its `mcp` block — the engine withdraws it — but do not build a workflow on a tool
|
|
255
272
|
that will not be there.
|
|
@@ -293,6 +310,10 @@ curl -X POST https://your-app.example.com/api/v1/mcp \
|
|
|
293
310
|
tool ships; catch with the `tools/list` diff in Verification.
|
|
294
311
|
- **Building an agent workflow on a verb that carries an `unimplementedAcknowledgement`** — it is
|
|
295
312
|
withdrawn, so the workflow's tool will simply not be there; catch with the acknowledgement row.
|
|
313
|
+
- **Describing a file upload in your own `mcp.description`, or expecting an agent to pass a
|
|
314
|
+
`fileId` it made up** — the engine derives an `…upload_grant.<field>` tool and appends the
|
|
315
|
+
`File fields:` note itself, and a fileId only ever comes from an upload; catch with the
|
|
316
|
+
`upload_grant.` grep on the live catalogue in Verification.
|
|
296
317
|
- **Treating named servers as cosmetic grouping** — each is a distinct RFC 8707 resource server,
|
|
297
318
|
so a token for one is REJECTED at another; that isolation is the reason to split, and it is
|
|
298
319
|
why a ref rename invalidates already-minted tokens.
|