@wildo-ai/platform-config-lib 1.1.5 → 1.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (138) hide show
  1. package/dist/esm/bootstrap/bootstrap.contracts.d.ts +3 -2
  2. package/dist/esm/bootstrap/bootstrap.contracts.d.ts.map +1 -1
  3. package/dist/esm/bootstrap/bootstrap.contracts.js +3 -2
  4. package/dist/esm/bootstrap/bootstrap.contracts.js.map +1 -1
  5. package/dist/esm/bootstrap/bootstrap.schemas.d.ts +47 -0
  6. package/dist/esm/bootstrap/bootstrap.schemas.d.ts.map +1 -1
  7. package/dist/esm/bootstrap/bootstrap.schemas.js +8 -0
  8. package/dist/esm/bootstrap/bootstrap.schemas.js.map +1 -1
  9. package/dist/esm/bootstrap/platform-runtime-env.contracts.d.ts +12 -1
  10. package/dist/esm/bootstrap/platform-runtime-env.contracts.d.ts.map +1 -1
  11. package/dist/esm/bootstrap/platform-runtime-env.contracts.js +12 -0
  12. package/dist/esm/bootstrap/platform-runtime-env.contracts.js.map +1 -1
  13. package/dist/esm/bootstrap/platform-store-preconnect.d.ts +37 -0
  14. package/dist/esm/bootstrap/platform-store-preconnect.d.ts.map +1 -0
  15. package/dist/esm/bootstrap/platform-store-preconnect.js +43 -0
  16. package/dist/esm/bootstrap/platform-store-preconnect.js.map +1 -0
  17. package/dist/esm/bootstrap/runtime-backing-service-access.d.ts.map +1 -1
  18. package/dist/esm/bootstrap/runtime-backing-service-access.js +8 -4
  19. package/dist/esm/bootstrap/runtime-backing-service-access.js.map +1 -1
  20. package/dist/esm/bootstrap/runtime-topology.contracts.d.ts +36 -3
  21. package/dist/esm/bootstrap/runtime-topology.contracts.d.ts.map +1 -1
  22. package/dist/esm/bootstrap/runtime-topology.contracts.js +36 -13
  23. package/dist/esm/bootstrap/runtime-topology.contracts.js.map +1 -1
  24. package/dist/esm/index.d.ts +1 -0
  25. package/dist/esm/index.d.ts.map +1 -1
  26. package/dist/esm/index.js +1 -0
  27. package/dist/esm/index.js.map +1 -1
  28. package/dist/esm/lockfile/lockfile-io.d.ts +7 -1
  29. package/dist/esm/lockfile/lockfile-io.d.ts.map +1 -1
  30. package/dist/esm/lockfile/lockfile-io.js +17 -3
  31. package/dist/esm/lockfile/lockfile-io.js.map +1 -1
  32. package/dist/esm/lockfile/materialize-infra-section.d.ts +27 -6
  33. package/dist/esm/lockfile/materialize-infra-section.d.ts.map +1 -1
  34. package/dist/esm/lockfile/materialize-infra-section.js +23 -10
  35. package/dist/esm/lockfile/materialize-infra-section.js.map +1 -1
  36. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.d.ts +455 -6
  37. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.d.ts.map +1 -1
  38. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.js +27 -0
  39. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.js.map +1 -1
  40. package/dist/esm/project-config/application-public-pricing-catalog.loader.d.ts +13 -0
  41. package/dist/esm/project-config/application-public-pricing-catalog.loader.d.ts.map +1 -0
  42. package/dist/esm/project-config/application-public-pricing-catalog.loader.js +56 -0
  43. package/dist/esm/project-config/application-public-pricing-catalog.loader.js.map +1 -0
  44. package/dist/esm/project-config/define-infra-env-config.d.ts +0 -27
  45. package/dist/esm/project-config/define-infra-env-config.d.ts.map +1 -1
  46. package/dist/esm/project-config/define-infra-env-config.js +0 -2
  47. package/dist/esm/project-config/define-infra-env-config.js.map +1 -1
  48. package/dist/esm/project-config/define-saas-config.d.ts +52 -0
  49. package/dist/esm/project-config/define-saas-config.d.ts.map +1 -1
  50. package/dist/esm/project-config/define-saas-config.js +65 -15
  51. package/dist/esm/project-config/define-saas-config.js.map +1 -1
  52. package/dist/esm/project-config/index.d.ts +3 -0
  53. package/dist/esm/project-config/index.d.ts.map +1 -1
  54. package/dist/esm/project-config/index.js +3 -0
  55. package/dist/esm/project-config/index.js.map +1 -1
  56. package/dist/esm/project-config/loader.d.ts +11 -0
  57. package/dist/esm/project-config/loader.d.ts.map +1 -1
  58. package/dist/esm/project-config/loader.js +34 -7
  59. package/dist/esm/project-config/loader.js.map +1 -1
  60. package/dist/esm/project-config/npm-version-range.d.ts +23 -0
  61. package/dist/esm/project-config/npm-version-range.d.ts.map +1 -0
  62. package/dist/esm/project-config/npm-version-range.js +175 -0
  63. package/dist/esm/project-config/npm-version-range.js.map +1 -0
  64. package/dist/esm/project-config/provider-companion-discovery.d.ts +256 -30
  65. package/dist/esm/project-config/provider-companion-discovery.d.ts.map +1 -1
  66. package/dist/esm/project-config/provider-companion-discovery.js +719 -40
  67. package/dist/esm/project-config/provider-companion-discovery.js.map +1 -1
  68. package/dist/esm/project-config/provider-runtime-artifacts.d.ts +125 -2
  69. package/dist/esm/project-config/provider-runtime-artifacts.d.ts.map +1 -1
  70. package/dist/esm/project-config/provider-runtime-artifacts.js +283 -66
  71. package/dist/esm/project-config/provider-runtime-artifacts.js.map +1 -1
  72. package/dist/esm/project-config/shared/backing-service-servability.d.ts +157 -0
  73. package/dist/esm/project-config/shared/backing-service-servability.d.ts.map +1 -0
  74. package/dist/esm/project-config/shared/backing-service-servability.js +256 -0
  75. package/dist/esm/project-config/shared/backing-service-servability.js.map +1 -0
  76. package/dist/esm/project-config/shared/backing-services.schemas.d.ts +62 -67
  77. package/dist/esm/project-config/shared/backing-services.schemas.d.ts.map +1 -1
  78. package/dist/esm/project-config/shared/backing-services.schemas.js +71 -68
  79. package/dist/esm/project-config/shared/backing-services.schemas.js.map +1 -1
  80. package/dist/esm/project-config/shared/csp-emit.d.ts.map +1 -1
  81. package/dist/esm/project-config/shared/csp-emit.js +41 -2
  82. package/dist/esm/project-config/shared/csp-emit.js.map +1 -1
  83. package/dist/esm/project-config/shared/infra-providers.schemas.d.ts +180 -4
  84. package/dist/esm/project-config/shared/infra-providers.schemas.d.ts.map +1 -1
  85. package/dist/esm/project-config/shared/infra-providers.schemas.js +40 -0
  86. package/dist/esm/project-config/shared/infra-providers.schemas.js.map +1 -1
  87. package/dist/esm/project-config/static-asset-import-noop.d.ts +26 -0
  88. package/dist/esm/project-config/static-asset-import-noop.d.ts.map +1 -0
  89. package/dist/esm/project-config/static-asset-import-noop.js +49 -0
  90. package/dist/esm/project-config/static-asset-import-noop.js.map +1 -0
  91. package/dist/esm/registry/companion-api.schemas.d.ts +0 -176
  92. package/dist/esm/registry/companion-api.schemas.d.ts.map +0 -1
  93. package/dist/esm/registry/companion-api.schemas.js.map +0 -1
  94. package/dist/esm/registry/index.d.ts +3 -1
  95. package/dist/esm/registry/index.d.ts.map +1 -1
  96. package/dist/esm/registry/index.js +3 -1
  97. package/dist/esm/registry/index.js.map +1 -1
  98. package/dist/esm/registry/local-checkout-source.d.ts +31 -0
  99. package/dist/esm/registry/local-checkout-source.d.ts.map +1 -0
  100. package/dist/esm/registry/local-checkout-source.js +45 -0
  101. package/dist/esm/registry/local-checkout-source.js.map +1 -0
  102. package/dist/esm/registry/lockfile-modules-section.schemas.d.ts +174 -14
  103. package/dist/esm/registry/lockfile-modules-section.schemas.d.ts.map +1 -1
  104. package/dist/esm/registry/lockfile-modules-section.schemas.js +120 -11
  105. package/dist/esm/registry/lockfile-modules-section.schemas.js.map +1 -1
  106. package/dist/esm/registry/module-artifact.schemas.d.ts +79 -0
  107. package/dist/esm/registry/module-artifact.schemas.d.ts.map +1 -1
  108. package/dist/esm/registry/module-artifact.schemas.js +36 -0
  109. package/dist/esm/registry/module-artifact.schemas.js.map +1 -1
  110. package/dist/esm/registry/module-manifest.schemas.d.ts +393 -7
  111. package/dist/esm/registry/module-manifest.schemas.d.ts.map +1 -1
  112. package/dist/esm/registry/module-manifest.schemas.js +488 -40
  113. package/dist/esm/registry/module-manifest.schemas.js.map +1 -1
  114. package/dist/esm/registry/module-search.schemas.d.ts +80 -0
  115. package/dist/esm/registry/module-search.schemas.d.ts.map +1 -0
  116. package/dist/esm/registry/module-search.schemas.js +112 -0
  117. package/dist/esm/registry/module-search.schemas.js.map +1 -0
  118. package/dist/esm/registry/registry-config.schemas.d.ts +16 -0
  119. package/dist/esm/registry/registry-config.schemas.d.ts.map +1 -1
  120. package/dist/esm/registry/registry-config.schemas.js +8 -0
  121. package/dist/esm/registry/registry-config.schemas.js.map +1 -1
  122. package/dist/esm/registry/registry-errors.d.ts +126 -2
  123. package/dist/esm/registry/registry-errors.d.ts.map +1 -1
  124. package/dist/esm/registry/registry-errors.js +183 -14
  125. package/dist/esm/registry/registry-errors.js.map +1 -1
  126. package/dist/esm/registry/registry-keys.schemas.d.ts +80 -0
  127. package/dist/esm/registry/registry-keys.schemas.d.ts.map +1 -0
  128. package/dist/esm/registry/registry-keys.schemas.js +68 -0
  129. package/dist/esm/registry/registry-keys.schemas.js.map +1 -0
  130. package/dist/esm/registry/registry-section-schemas.constants.d.ts +25 -3
  131. package/dist/esm/registry/registry-section-schemas.constants.d.ts.map +1 -1
  132. package/dist/esm/workspace-scope/workspace-homes.schemas.d.ts +13 -11
  133. package/dist/esm/workspace-scope/workspace-homes.schemas.d.ts.map +1 -1
  134. package/dist/esm/workspace-scope/workspace-homes.schemas.js +2 -2
  135. package/dist/esm/workspace-scope/workspace-homes.schemas.js.map +1 -1
  136. package/package.json +7 -7
  137. package/dist/esm/registry/companion-api.schemas.js +0 -165
  138. package/dist/tsconfig.build.tsbuildinfo +0 -1
@@ -1,7 +1,9 @@
1
1
  import { createRequire } from 'node:module';
2
2
  import { existsSync, readFileSync } from 'node:fs';
3
3
  import { dirname, join, resolve } from 'node:path';
4
- import { ProviderCompanionContributionSchema, describeCaughtError } from '@wildo-ai/saas-models';
4
+ import { BUILTIN_PROVIDER_PROTOCOL, SYSTEM_OF_RECORD_FACET_MODULE_NOT_DISCOVERED, ProviderAugmentationContributionSchema, ProviderCompanionContributionSchema, describeCaughtError, findProviderSharedConnectionConflicts } from '@wildo-ai/saas-models';
5
+ import { providerOAuth2TokenEndpointHostsIntersect } from '@wildo-ai/external-connectors-models';
6
+ import { satisfiesNpmVersionRange } from './npm-version-range.js';
5
7
  import { loadPackageCompanionExport, resolvePackageCompanionEntryPath } from './loader.js';
6
8
  /**
7
9
  * `providerPackage` was added by #330 and is the point of that slice on this file.
@@ -32,33 +34,15 @@ export var ProviderContributionOwnerKind;
32
34
  /**
33
35
  * Package-name prefixes whose dependencies are treated as provider packages.
34
36
  *
35
- * `@wildo-ai/provider-` is the framework convention (#337 D3). An application's OWN provider packages
37
+ * `@wildo-ai/provider-` is the framework convention (#337 D3), and the name a registry provider's facet packages
38
+ * carry in `providers-registry/<ref>/` before an install renames them into the application's scope. An application's OWN provider packages
36
39
  * are admitted through the scope of its root manifest — an application published as `@acme/…` gets
37
- * `@acme/provider-…` for free — so a private provider needs no configuration to be discovered, and a
38
- * dependency belonging to somebody else's scope is never executed by this walk.
40
+ * `@acme/provider-…` for free — so a private provider needs no configuration to be discovered, and any other
41
+ * dependency is never executed by this walk unless the application lists it in `providers.packages` (#1676).
39
42
  */
40
43
  export const FRAMEWORK_PROVIDER_PACKAGE_PREFIX = '@wildo-ai/provider-';
41
44
  /**
42
- * The framework's own scraped catalogue, admitted by exact NAME because it does not fit the prefix.
43
- *
44
- * Paul decided on 2026-09-06 that the transposed catalogue ships as ONE package with a subpath per
45
- * vendor — `@wildo-ai/providers/slack` — rather than as 697 packages. The prefix above predates that
46
- * decision and describes the shape it replaced, and `'@wildo-ai/providers'.startsWith('@wildo-ai/provider-')`
47
- * is **false**: the `s` is not a `-`.
48
- *
49
- * So discovery could not see the catalogue at all. What it DID admit, measured 2026-09-07, was
50
- * `@wildo-ai/provider-simulators` — the test doubles — and nothing else in the repository matches the
51
- * prefix. A rule that admits only the simulator of a thing is worse than no rule, because it looks
52
- * like coverage.
53
- *
54
- * An exact name rather than a loosened prefix (`@wildo-ai/provider`, no hyphen) on purpose: that
55
- * would also admit any future `@wildo-ai/providerfoo`, and the catalogue is ONE known package, not a
56
- * family. The prefix keeps serving the family it was written for — an application's own
57
- * `@acme/provider-thing`.
58
- */
59
- export const FRAMEWORK_PROVIDER_CATALOGUE_PACKAGE = '@wildo-ai/providers';
60
- /**
61
- * The ENGINE's own provider barrel, admitted exactly as the catalogue is.
45
+ * The ENGINE's own provider barrel, admitted by exact NAME.
62
46
  *
63
47
  * The engine ships 23 providers and exports them through `./companion` — the same shape every
64
48
  * provider package uses. Discovery did not admit it, so an application that wanted `resend` declared
@@ -67,10 +51,55 @@ export const FRAMEWORK_PROVIDER_CATALOGUE_PACKAGE = '@wildo-ai/providers';
67
51
  * two lacked; config sync refused a scoped-but-uncontributed provider, so it was not optional either
68
52
  * (#358).
69
53
  *
70
- * A NAME rather than a prefix, for the reason the catalogue's own note gives: this is one known
71
- * package, not a family.
54
+ * A NAME rather than a loosened prefix (`@wildo-ai/provider`, no hyphen, or `@wildo-ai/external-connectors-`): this
55
+ * is one known package, not a family, and a prefix wide enough to reach it would also admit whatever else is later
56
+ * published under it.
57
+ *
58
+ * Until #2019 the transposed provider catalogue was admitted by exact name beside this one — ONE package with a subpath
59
+ * per vendor, whose name did not start with `@wildo-ai/provider-` (the `s` is not a `-`). It is archived; a provider
60
+ * the framework distributes now lives in `providers-registry/<ref>/` and reaches an application as its own copy, a
61
+ * `<scope>/provider-<ref>` package the scope prefix admits.
72
62
  */
73
63
  export const FRAMEWORK_ENGINE_PROVIDER_PACKAGE = '@wildo-ai/external-connectors-private';
64
+ /**
65
+ * The framework's SYSTEM-OF-RECORD library (#2013): the vendor facets — Odoo, SAP S/4HANA, Dataverse, Business
66
+ * Central, NetSuite, Salesforce, generic OData — as an opt-in package, admitted by exact NAME like the engine barrel above.
67
+ *
68
+ * The facets used to ride inside the provider catalogue, and discovery found them only because the catalogue was
69
+ * admitted by name. Moving them out without this line would have dropped Odoo's facet from the provider-runtime
70
+ * artifact, and the backend refuses a declared instance whose vendor has no facet (`VENDOR_HAS_NO_FACET`).
71
+ *
72
+ * It is also the ONLY package whose `./systems-of-record` module is recorded without an instance asking for it —
73
+ * see {@link isAdmittedSystemOfRecordFacetModule}.
74
+ */
75
+ export const FRAMEWORK_SYSTEMS_OF_RECORD_PACKAGE = '@wildo-ai/systems-of-record';
76
+ /**
77
+ * What discovery found for one package the application LISTS in `providers.packages` (#1676). Only
78
+ * {@link ProviderPackageListingStatus.ADMITTED} is acceptable: every other status is a `wildo config sync` refusal
79
+ * naming the package, because a listing is an explicit decision and a listing that admits nothing is a mistake the
80
+ * author believes is working.
81
+ */
82
+ export var ProviderPackageListingStatus;
83
+ (function (ProviderPackageListingStatus) {
84
+ /** Walked, and it ships a provider contribution, an augmentation or a `./systems-of-record` module. */
85
+ ProviderPackageListingStatus["ADMITTED"] = "admitted";
86
+ /** Neither the application root nor any runtime owner depends on it, so nothing could install or import it. */
87
+ ProviderPackageListingStatus["NOT_A_DEPENDENCY"] = "not-a-dependency";
88
+ /** Declared as a dependency but not found under `node_modules` — run the package manager's install. */
89
+ ProviderPackageListingStatus["NOT_INSTALLED"] = "not-installed";
90
+ /** Its `./companion` door exists and could not be read; the reason is carried. */
91
+ ProviderPackageListingStatus["UNREADABLE"] = "unreadable";
92
+ /** Walked, and it ships nothing discovery reads: no provider contribution, no augmentation, no facet module. */
93
+ ProviderPackageListingStatus["CONTRIBUTES_NOTHING"] = "contributes-nothing";
94
+ /**
95
+ * A name discovery walks by itself (`@wildo-ai/provider-*`, the engine barrel, the systems-of-record library, the
96
+ * application's own scope named `<scope>/provider-*`). Refused rather than recorded: the listing changes nothing, and recording it would put framework code in
97
+ * the lock as a third-party admission.
98
+ */
99
+ ProviderPackageListingStatus["ALREADY_WALKED"] = "already-walked";
100
+ /** One of the application's own runtime packages — walked as a runtime owner, never as a provider package. */
101
+ ProviderPackageListingStatus["RUNTIME_OWNER"] = "runtime-owner";
102
+ })(ProviderPackageListingStatus || (ProviderPackageListingStatus = {}));
74
103
  /**
75
104
  * The runtime targets an application's SCOPES imply for one provider ref.
76
105
  *
@@ -100,6 +129,16 @@ export const FRAMEWORK_ENGINE_PROVIDER_PACKAGE = '@wildo-ai/external-connectors-
100
129
  * Applies to contributions discovered from a PACKAGE. A runtime owner's own companion barrel keeps
101
130
  * whatever it declares: that is the application's own file talking about itself, and an application
102
131
  * package is entitled to state a target the scopes do not.
132
+ *
133
+ * ## A browser target is declared, then filtered by the scopes (#1700)
134
+ *
135
+ * A package CAN know one thing about a browser target: a facet's `frontendService` target names a service TYPE (the
136
+ * application, the website, the documentation site), which is the facet's own contract. So a package contribution
137
+ * keeps a declared `frontendService` target wherever a frontend service of that type scopes the ref, and the server
138
+ * scopes are consulted for the server runtimes only — and only for a contribution that declares one. Deriving both
139
+ * halves from the server scopes dropped a facet's frontend target (so no frontend scope could ever find it) and
140
+ * gave the facet a `backend` target whenever the vendor's backend part was scoped, where it collided with that
141
+ * part's secret contract. See {@link resolvePackageContributionRuntimeTargets}.
103
142
  */
104
143
  function resolveScopeImpliedRuntimeTargets(providerRef, saasConfig) {
105
144
  const scopes = saasConfig.providers?.scopes;
@@ -120,15 +159,51 @@ function resolveScopeImpliedRuntimeTargets(providerRef, saasConfig) {
120
159
  }
121
160
  return targets;
122
161
  }
162
+ /**
163
+ * A PACKAGE contribution's runtime targets: server targets derived from the application's scopes (and none when it
164
+ * declares no server target at all), and a declared browser target kept only where the application actually scopes
165
+ * the ref on a frontend service of that TYPE. See {@link resolveScopeImpliedRuntimeTargets}.
166
+ *
167
+ * The browser half is filtered for the same reason the server half is derived: an installed package speaks for every
168
+ * application, and a target no scope asked for is not this application's. Keeping an unscoped facet's target made
169
+ * validation refuse `wildo config sync` for any application that installed a provider package without a service of the
170
+ * facet's type — a backend-only application, or one with no website for a website facet.
171
+ */
172
+ export function resolvePackageContributionRuntimeTargets(contribution, saasConfig) {
173
+ const declaresServerTarget = contribution.runtimeTargets.some((target) => target.kind !== 'frontendService');
174
+ const scopedFrontendTypes = new Set(Object.entries(saasConfig.providers?.scopes?.frontendServices ?? {})
175
+ .filter(([, scope]) => scope?.providers?.[contribution.ref] !== undefined)
176
+ .map(([serviceKey]) => saasConfig.services?.[serviceKey]?.frontendType)
177
+ .filter((frontendType) => frontendType !== undefined));
178
+ const scopedFrontendTargets = contribution.runtimeTargets.filter((target) => target.kind === 'frontendService' && scopedFrontendTypes.has(target.serviceType));
179
+ return [
180
+ ...(declaresServerTarget ? resolveScopeImpliedRuntimeTargets(contribution.ref, saasConfig) : []),
181
+ ...scopedFrontendTargets,
182
+ ];
183
+ }
123
184
  export async function discoverSaasProviderCompanionContributions(input) {
124
185
  const contributions = [];
186
+ const optedInFacetPackages = systemOfRecordFacetAugmentationPackages(input.saasConfig.systemsOfRecord);
125
187
  const runtimeOwnerTargets = resolveContributionTargets(input.saasRoot, input.saasConfig);
126
188
  const unreadableOwners = [];
127
- for (const target of [
128
- ...runtimeOwnerTargets,
129
- // Unfiltered roots, NOT `runtimeOwnerTargets` — see `resolveRuntimeOwnerPackageRoots` (#1300).
130
- ...resolveProviderPackageTargets(input.saasRoot, resolveRuntimeOwnerPackageRoots(input.saasRoot, input.saasConfig)),
131
- ]) {
189
+ const augmentations = [];
190
+ const systemOfRecordFacetModules = new Set();
191
+ const listedPackageNames = input.saasConfig.providers?.packages ?? [];
192
+ const packageTargets = resolveProviderPackageTargets(input.saasRoot,
193
+ // Unfiltered roots, NOT `runtimeOwnerTargets` — see `resolveRuntimeOwnerPackageRoots` (#1300).
194
+ resolveRuntimeOwnerPackageRoots(input.saasRoot, input.saasConfig), listedPackageNames);
195
+ /** What each walked PACKAGE target shipped, by package name — the evidence a listing's status is read from. */
196
+ const packageFindings = new Map();
197
+ for (const target of [...runtimeOwnerTargets, ...packageTargets.targets]) {
198
+ // Before the companion door is read, so a package with facets and no companion exports is still found. Read for
199
+ // EVERY walked target — the runtime owners included — and recorded only when admitted (#2013).
200
+ const facetModule = readSystemOfRecordFacetModuleSpecifier(target.packageRoot);
201
+ if (facetModule !== undefined && isAdmittedSystemOfRecordFacetModule(facetModule, optedInFacetPackages)) {
202
+ systemOfRecordFacetModules.add(facetModule);
203
+ }
204
+ const isPackage = target.kind === ProviderContributionOwnerKind.PROVIDER_PACKAGE;
205
+ if (isPackage)
206
+ packageFindings.set(target.key, { shipsSomething: facetModule !== undefined });
132
207
  const loaded = await tryLoadRuntimeOwnerCompanionExports(target.packageRoot);
133
208
  if (loaded.unreadable !== undefined) {
134
209
  unreadableOwners.push({
@@ -136,12 +211,25 @@ export async function discoverSaasProviderCompanionContributions(input) {
136
211
  packageRoot: target.packageRoot,
137
212
  reason: loaded.unreadable,
138
213
  });
214
+ if (isPackage)
215
+ packageFindings.set(target.key, { shipsSomething: facetModule !== undefined, unreadable: loaded.unreadable });
139
216
  continue;
140
217
  }
141
218
  if (!loaded.exports) {
142
219
  continue;
143
220
  }
144
221
  const parsedContributions = ProviderCompanionContributionSchema.array().parse(loaded.exports.providerContributions ?? []);
222
+ if (isPackage && (parsedContributions.length > 0 || (loaded.exports.providerAugmentations ?? []).length > 0)) {
223
+ packageFindings.set(target.key, { shipsSomething: true });
224
+ }
225
+ const owner = { kind: target.kind, key: target.key, packageRoot: target.packageRoot };
226
+ const ownerVersion = readPackageVersion(target.packageRoot);
227
+ augmentations.push(...ProviderAugmentationContributionSchema.array().parse(loaded.exports.providerAugmentations ?? [])
228
+ .map((augmentation) => ({
229
+ ...augmentation,
230
+ owner,
231
+ ...(ownerVersion === undefined ? {} : { packageVersion: ownerVersion }),
232
+ })));
145
233
  // A PACKAGE cannot know this application's runtime topology, so its declared targets are a
146
234
  // default and the SCOPES are the answer. A runtime owner's own barrel keeps what it declares —
147
235
  // see `resolveScopeImpliedRuntimeTargets`.
@@ -149,7 +237,7 @@ export async function discoverSaasProviderCompanionContributions(input) {
149
237
  contributions.push(...parsedContributions.map((contribution) => ({
150
238
  ...contribution,
151
239
  runtimeTargets: derivesTargetsFromScopes
152
- ? resolveScopeImpliedRuntimeTargets(contribution.ref, input.saasConfig)
240
+ ? resolvePackageContributionRuntimeTargets(contribution, input.saasConfig)
153
241
  : contribution.runtimeTargets,
154
242
  owner: {
155
243
  kind: target.kind,
@@ -158,7 +246,127 @@ export async function discoverSaasProviderCompanionContributions(input) {
158
246
  },
159
247
  })));
160
248
  }
161
- return { contributions, unreadableOwners };
249
+ return {
250
+ contributions,
251
+ unreadableOwners,
252
+ augmentations,
253
+ systemOfRecordFacetModules: [...systemOfRecordFacetModules].sort(),
254
+ listedProviderPackages: listedPackageNames.map((packageName) => describeListedProviderPackage(packageName, packageTargets, packageFindings)),
255
+ };
256
+ }
257
+ /** What discovery found for one listed package (#1676) — see {@link ProviderPackageListingStatus}. */
258
+ function describeListedProviderPackage(packageName, packageTargets, packageFindings) {
259
+ if (packageTargets.ownPackageNames.has(packageName))
260
+ return { packageName, status: ProviderPackageListingStatus.RUNTIME_OWNER };
261
+ if (packageTargets.admittedByName(packageName))
262
+ return { packageName, status: ProviderPackageListingStatus.ALREADY_WALKED };
263
+ if (!packageTargets.dependencyNames.has(packageName))
264
+ return { packageName, status: ProviderPackageListingStatus.NOT_A_DEPENDENCY };
265
+ const target = packageTargets.targets.find((candidate) => candidate.key === packageName);
266
+ if (target === undefined)
267
+ return { packageName, status: ProviderPackageListingStatus.NOT_INSTALLED };
268
+ const version = readPackageVersion(target.packageRoot);
269
+ const versioned = version === undefined ? {} : { packageVersion: version };
270
+ const finding = packageFindings.get(packageName);
271
+ if (finding?.unreadable !== undefined)
272
+ return { packageName, status: ProviderPackageListingStatus.UNREADABLE, reason: finding.unreadable, ...versioned };
273
+ if (finding?.shipsSomething !== true)
274
+ return { packageName, status: ProviderPackageListingStatus.CONTRIBUTES_NOTHING, ...versioned };
275
+ return { packageName, status: ProviderPackageListingStatus.ADMITTED, ...versioned };
276
+ }
277
+ /**
278
+ * The export a package declares to contribute system-of-record vendor facets or facet augmentations. The manifest
279
+ * key of saas-models' `SYSTEM_OF_RECORD_FACET_MODULE_SUBPATH`, restated rather than imported so manifest discovery
280
+ * does not load the external-data model graph to read one string; a test holds the two equal (#1675).
281
+ */
282
+ const SYSTEM_OF_RECORD_FACET_SUBPATH = './systems-of-record';
283
+ /**
284
+ * Every package an instance opts into through `systemsOfRecord.<name>.facetAugmentations` — the application's OWN
285
+ * augmentation packages, and the only ones besides {@link FRAMEWORK_SYSTEMS_OF_RECORD_PACKAGE} whose facet module
286
+ * discovery records.
287
+ */
288
+ function systemOfRecordFacetAugmentationPackages(systemsOfRecord) {
289
+ const packages = new Set();
290
+ for (const declaration of Object.values(systemsOfRecord ?? {})) {
291
+ for (const packageName of declaration?.facetAugmentations ?? [])
292
+ packages.add(packageName);
293
+ }
294
+ return packages;
295
+ }
296
+ /**
297
+ * Whether a walked package's `./systems-of-record` module may reach the provider-runtime artifact (#2013).
298
+ *
299
+ * A facet module is where a system of record's partition, credential kinds and dialect come from, so the modules
300
+ * recorded decide how a tenant's rows are confined — and every one of them is IMPORTED by the backend at boot. Two
301
+ * sources qualify, and nothing else:
302
+ *
303
+ * - the framework library, by its exact name — the base facets every declared instance reads;
304
+ * - a package an instance of THIS application names in `facetAugmentations` — the application's own augmentation
305
+ * packages. The opt-in is the admission: the package still has to be walked (named `<scope>/provider-*`, or listed
306
+ * in `providers.packages`), and a named package discovery did not record is refused by
307
+ * `describeUndiscoveredFacetAugmentationPackages`.
308
+ *
309
+ * Before #2013 any walked package exporting the subpath was recorded: the catalogue (which carried the facets), any
310
+ * `@wildo-ai/provider-*` package, the application's own `<scope>/provider-*` copies, its runtime owners. With the
311
+ * facets in their own library, that breadth only let a package the application never asked for present a BASE facet
312
+ * — and a second base facet for a vendor refuses every instance of it (`FACET_BASE_CONFLICT`). Registry providers
313
+ * copied into an application must never carry system-of-record content (#2012), so they are not admitted either.
314
+ *
315
+ * assurance-control: WILDO.SECURITY.FAIL_CLOSED — a facet module reaches the backend only from the framework library
316
+ * or from a package the application's own system-of-record declaration names.
317
+ */
318
+ function isAdmittedSystemOfRecordFacetModule(facetModule, optedInFacetPackages) {
319
+ const packageName = facetModule.slice(0, -SYSTEM_OF_RECORD_FACET_SUBPATH.slice(1).length);
320
+ return packageName === FRAMEWORK_SYSTEMS_OF_RECORD_PACKAGE || optedInFacetPackages.has(packageName);
321
+ }
322
+ /**
323
+ * The facet module a package root declares — `<name>/systems-of-record` — or `undefined`. Read from the
324
+ * MANIFEST, never by loading: a build-time consumer has no business evaluating a vendor facet to learn that
325
+ * one exists, and loading would make discovery depend on the package compiling.
326
+ */
327
+ export function readSystemOfRecordFacetModuleSpecifier(packageRoot) {
328
+ let manifest;
329
+ try {
330
+ manifest = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
331
+ }
332
+ catch {
333
+ // Unreadable or absent: the companion walk already tolerates that, and a package we could not read is
334
+ // not one we can say anything about.
335
+ return undefined;
336
+ }
337
+ if (manifest.exports?.[SYSTEM_OF_RECORD_FACET_SUBPATH] === undefined)
338
+ return undefined;
339
+ if (typeof manifest.name !== 'string' || manifest.name.length === 0)
340
+ return undefined;
341
+ return `${manifest.name}${SYSTEM_OF_RECORD_FACET_SUBPATH.slice(1)}`;
342
+ }
343
+ /**
344
+ * Every discovered provider's COMPLIANCE PROFILE, keyed by ref (#1708) — the one door the compliance readers (the
345
+ * evidence collector, the companion's drafting brief) learn profiles through, WITHOUT loading a provider module.
346
+ *
347
+ * A backend contribution's own `complianceProfile` is preferred; a frontend facet's `frontendEntry.complianceProfile`
348
+ * (#1743) answers for a ref that has only a browser part. The first contribution that carries one wins, in discovery
349
+ * order — the application's own runtime owners before packages — so an application shipping its own module for a
350
+ * ref states that ref's facts. A ref whose contributions carry none is ABSENT from the map, which a reader reports as
351
+ * "declares no profile", distinct from an UNDETERMINED one.
352
+ */
353
+ export function providerComplianceProfilesFromContributions(contributions) {
354
+ const profiles = {};
355
+ for (const contribution of contributions) {
356
+ if (profiles[contribution.ref] === undefined && contribution.complianceProfile !== undefined)
357
+ profiles[contribution.ref] = contribution.complianceProfile;
358
+ }
359
+ for (const contribution of contributions) {
360
+ const frontendProfile = contribution.frontendEntry?.complianceProfile;
361
+ if (profiles[contribution.ref] === undefined && frontendProfile !== undefined)
362
+ profiles[contribution.ref] = frontendProfile;
363
+ }
364
+ return profiles;
365
+ }
366
+ /** See {@link providerComplianceProfilesFromContributions}. Discovery's unreadable owners are returned so a reader can say what it could not see. */
367
+ export async function resolveProviderComplianceProfiles(input) {
368
+ const { contributions, unreadableOwners } = await discoverSaasProviderCompanionContributions(input);
369
+ return { profilesByProviderRef: providerComplianceProfilesFromContributions(contributions), unreadableOwners };
162
370
  }
163
371
  /**
164
372
  * Walk an application's provider contributions and VALIDATE them — one step, because the two must
@@ -178,17 +386,50 @@ export async function discoverSaasProviderCompanionContributions(input) {
178
386
  * discovery and the real validation they exist to check.
179
387
  */
180
388
  export async function resolveValidatedSaasProviderContributions(input) {
181
- const { contributions, unreadableOwners } = await discoverSaasProviderCompanionContributions(input);
389
+ const { contributions, unreadableOwners, augmentations, systemOfRecordFacetModules, listedProviderPackages } = await discoverSaasProviderCompanionContributions(input);
182
390
  validateDiscoveredSaasProviderContributions({
183
391
  saasConfig: input.saasConfig,
184
392
  discoveredContributions: contributions,
393
+ discoveredAugmentations: augmentations,
185
394
  unreadableOwners,
395
+ listedProviderPackages,
396
+ systemOfRecordFacetModules,
186
397
  });
187
- return contributions;
398
+ return {
399
+ contributions,
400
+ augmentations: selectOptedInProviderAugmentations(input.saasConfig, augmentations),
401
+ systemOfRecordFacetModules,
402
+ admittedProviderPackages: listedProviderPackages
403
+ .filter((listed) => listed.status === ProviderPackageListingStatus.ADMITTED)
404
+ .map(({ packageName, packageVersion }) => ({ packageName, ...(packageVersion === undefined ? {} : { packageVersion }) }))
405
+ .sort((left, right) => left.packageName.localeCompare(right.packageName)),
406
+ advisories: validateProviderSharedConnections({ saasConfig: input.saasConfig, discoveredContributions: contributions }).advisories,
407
+ };
408
+ }
409
+ /**
410
+ * The discovered augmentations the application names under `providers.augmentations` — the ONLY ones that may
411
+ * reach an artifact (#1672). Installing a package decides nothing; this is where that sentence is enforced for
412
+ * every caller, and {@link materializeSaasProviderRuntimeArtifacts} applies it again so an artifact can never be
413
+ * built from an unfiltered list.
414
+ *
415
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — third-party operations reach a provider's grant
416
+ * only through the application's explicit, per-provider opt-in.
417
+ */
418
+ export function selectOptedInProviderAugmentations(saasConfig, augmentations) {
419
+ const optIns = saasConfig.providers?.augmentations ?? {};
420
+ return augmentations
421
+ .filter((augmentation) => Object.hasOwn(optIns, augmentation.augments)
422
+ && (optIns[augmentation.augments] ?? []).includes(augmentation.packageName))
423
+ .sort((left, right) => left.augments.localeCompare(right.augments) || left.packageName.localeCompare(right.packageName));
188
424
  }
189
425
  export function validateDiscoveredSaasProviderContributions(input) {
190
426
  const { saasConfig, discoveredContributions } = input;
191
427
  const errors = [];
428
+ errors.push(...describeRefusedProviderPackageListings(input.listedProviderPackages ?? []));
429
+ if (input.systemOfRecordFacetModules !== undefined) {
430
+ errors.push(...describeUndiscoveredSystemsOfRecordLibrary(saasConfig.systemsOfRecord ?? {}, input.systemOfRecordFacetModules));
431
+ errors.push(...describeUndiscoveredFacetAugmentationPackages(saasConfig.systemsOfRecord ?? {}, input.systemOfRecordFacetModules));
432
+ }
192
433
  const declaredModuleIds = new Set(Object.keys(saasConfig.modules ?? {}));
193
434
  const declaredServiceKeys = new Set(Object.keys(saasConfig.services ?? {}));
194
435
  const serviceKeyToFrontendType = new Map(Object.entries(saasConfig.services ?? {})
@@ -289,11 +530,308 @@ export function validateDiscoveredSaasProviderContributions(input) {
289
530
  matchesTarget: (target) => target.kind === 'worker' && target.workerKey === workerKey,
290
531
  });
291
532
  }
533
+ validateProviderAugmentationOptIns({
534
+ errors,
535
+ saasConfig,
536
+ discoveredContributions,
537
+ discoveredAugmentations: input.discoveredAugmentations ?? [],
538
+ });
539
+ errors.push(...validateProviderSharedConnections({ saasConfig, discoveredContributions }).errors);
292
540
  if (errors.length > 0) {
293
541
  throw new Error(`Provider companion-export discovery validation failed:\n- ${errors.join('\n- ')}`
294
542
  + describeUnreadableOwnersForRefusal(input.unreadableOwners ?? []));
295
543
  }
296
544
  }
545
+ /**
546
+ * `wildo config sync`'s half of a declared shared connection (#1725): what can be decided from static
547
+ * declarations, before anything is recorded or loaded.
548
+ *
549
+ * REFUSED, each naming both sides:
550
+ * - a ref listed in two connections, or a base listed as a member (also refused by the schema; repeated here so
551
+ * a configuration that reached discovery without passing the schema is judged by the same predicate);
552
+ * - a runtime scope that declares a member and not its base — the base's module is what connects, refreshes
553
+ * and revokes the grant, so a host holding only the member could spend it and never renew it;
554
+ * - a system-of-record instance as a member or base — a system of record authenticates as the DEPLOYMENT's
555
+ * service identity and is never a delegated grant (#1055, #1738);
556
+ * - a base that declares no `REST_API` binding (no OAuth client to own);
557
+ * - a member whose token endpoint can only resolve to hosts the base's cannot — a different authorization
558
+ * server, whose refresh tokens the base's server would never honour.
559
+ *
560
+ * REPORTED (advisories): a member's own OAuth2 client, inert while it is a member; a vendor label that differs
561
+ * from the base's (display only until #1673); an authorization-server comparison the static shapes cannot
562
+ * make, which the registry repeats on the loaded modules at boot.
563
+ *
564
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — refs are admitted to one delegated grant only
565
+ * when they can genuinely share it.
566
+ */
567
+ export function validateProviderSharedConnections(input) {
568
+ const errors = [];
569
+ const advisories = [];
570
+ const connections = input.saasConfig.providers?.sharedConnections ?? {};
571
+ if (Object.keys(connections).length === 0)
572
+ return { errors, advisories };
573
+ errors.push(...findProviderSharedConnectionConflicts(connections).map((conflict) => `providers.sharedConnections: ${conflict.message}`));
574
+ const scopes = input.saasConfig.providers?.scopes ?? {};
575
+ const spendingScopes = [
576
+ ['backend', scopes.backend?.providers],
577
+ ['companion', scopes.companion?.providers],
578
+ ...Object.entries(scopes.minions ?? {}).map(([key, scope]) => [`minions.${key}`, scope.providers]),
579
+ ...Object.entries(scopes.workers ?? {}).map(([key, scope]) => [`workers.${key}`, scope.providers]),
580
+ ];
581
+ const systemsOfRecord = new Set(Object.keys(input.saasConfig.systemsOfRecord ?? {}));
582
+ const contributionOf = (ref) => input.discoveredContributions.find((contribution) => contribution.ref === ref);
583
+ for (const [baseRef, connection] of Object.entries(connections).sort(([left], [right]) => left.localeCompare(right))) {
584
+ for (const ref of [baseRef, ...connection.refs]) {
585
+ if (systemsOfRecord.has(ref)) {
586
+ errors.push(`providers.sharedConnections."${baseRef}" names "${ref}", which is a system-of-record instance. A system of record `
587
+ + 'authenticates as the deployment\'s own service identity and is never a delegated connection; remove it.');
588
+ }
589
+ }
590
+ for (const [scopeLabel, providers] of spendingScopes) {
591
+ if (providers === undefined)
592
+ continue;
593
+ const scopedMembers = connection.refs.filter((ref) => Object.hasOwn(providers, ref));
594
+ if (scopedMembers.length > 0 && !Object.hasOwn(providers, baseRef)) {
595
+ errors.push(`providers.scopes.${scopeLabel} declares ${scopedMembers.map((ref) => `"${ref}"`).join(', ')} of the shared connection "${baseRef}" `
596
+ + `but not "${baseRef}" itself. The base's module connects, refreshes and revokes the connection's grant, so every runtime `
597
+ + 'that spends it must load the base too; scope it there.');
598
+ }
599
+ }
600
+ const base = contributionOf(baseRef);
601
+ if (base !== undefined && !base.protocols.includes(BUILTIN_PROVIDER_PROTOCOL.REST_API)) {
602
+ errors.push(`providers.sharedConnections names "${baseRef}" as a base, and it declares no ${BUILTIN_PROVIDER_PROTOCOL.REST_API} binding. `
603
+ + 'A shared connection is owned by the base\'s connected-account OAuth2 client, which only a REST binding carries.');
604
+ continue;
605
+ }
606
+ for (const memberRef of connection.refs) {
607
+ const member = contributionOf(memberRef);
608
+ if (member === undefined || base === undefined)
609
+ continue;
610
+ const memberVendor = member.identity?.vendor;
611
+ const baseVendor = base.identity?.vendor;
612
+ if (memberVendor !== undefined && baseVendor !== undefined && memberVendor !== baseVendor) {
613
+ advisories.push(`"${memberRef}" (vendor "${memberVendor}") is a member of the shared connection "${baseRef}" (vendor "${baseVendor}"). `
614
+ + 'Membership is the declaration, not the vendor label, so this is reported only.');
615
+ }
616
+ if (member.oauth2TokenEndpointHosts !== undefined) {
617
+ advisories.push(`"${memberRef}" declares its own OAuth2 client; while it is a member of "${baseRef}" that client and its client-id and `
618
+ + `client-secret slots are inert — "${baseRef}"'s client connects and refreshes the one grant.`);
619
+ }
620
+ const baseHosts = base.oauth2TokenEndpointHosts;
621
+ const memberHosts = member.oauth2TokenEndpointHosts;
622
+ if (memberHosts === undefined)
623
+ continue;
624
+ const agrees = baseHosts === undefined ? undefined : providerOAuth2TokenEndpointHostsIntersect(baseHosts, memberHosts);
625
+ if (agrees === false) {
626
+ errors.push(`"${memberRef}" cannot join the shared connection "${baseRef}": its token endpoint resolves to `
627
+ + `${describeTokenEndpointHosts(memberHosts)} and "${baseRef}"'s to ${describeTokenEndpointHosts(baseHosts)}. `
628
+ + 'Those are different authorization servers, and a grant one of them issued cannot be renewed by the other.');
629
+ }
630
+ else if (agrees === undefined) {
631
+ advisories.push(`Whether "${memberRef}" and "${baseRef}" share an authorization server cannot be decided from their declarations; `
632
+ + 'the provider registry compares their token endpoints when the application boots.');
633
+ }
634
+ }
635
+ }
636
+ return { errors, advisories };
637
+ }
638
+ function describeTokenEndpointHosts(hosts) {
639
+ const parts = [...hosts.exact, ...hosts.suffixes.map((suffix) => `*${suffix}`)];
640
+ return parts.length === 0 ? '(no host)' : parts.join(', ');
641
+ }
642
+ /**
643
+ * Keys a companion augmentation record may carry. `ProviderAugmentationContributionSchema` is LOOSE — a newer
644
+ * producer's additive field must ride through an older consumer — so a key that belongs to the base provider
645
+ * would pass the schema silently. These are refused by name here, at `config sync`, before anything is
646
+ * recorded: the runtime reader refuses the same keys on the module itself, and the two refusals are
647
+ * deliberately redundant, because the companion record is what a reviewer reads and the module is what runs.
648
+ */
649
+ const BASE_OWNED_AUGMENTATION_RECORD_KEYS = {
650
+ ref: 'the provider\'s own ref (an augmentation names the base in `augments`)',
651
+ identity: 'the provider\'s identity',
652
+ protocols: 'a protocol binding',
653
+ baseUrl: 'a base URL',
654
+ oauth2: 'an OAuth2 block',
655
+ secretsContractShape: 'a secrets contract',
656
+ secretsContract: 'a secrets contract',
657
+ engineCapabilities: 'an engine capability',
658
+ providerCapabilities: 'a provider capability',
659
+ admissibleConnections: 'the connections a provider admits',
660
+ runtimeTargets: 'the runtimes a provider reaches (an augmentation applies wherever its base is scoped)',
661
+ frontendEntry: 'a frontend provider entry',
662
+ };
663
+ /**
664
+ * `wildo config sync`'s half of the augmentation opt-in (#1672): every name under `providers.augmentations`
665
+ * must be a package this walk discovered, declaring an admissible augmentation OF THAT REF, of a provider the
666
+ * application scopes and that runs REST operations — and no two opted-in packages may add one operation id.
667
+ *
668
+ * Everything here is decided from STATIC declarations, without loading a line of the augmenting package: the
669
+ * operation ids are stated in the companion record precisely so a collision is refused here rather than at the
670
+ * first call. The runtime loader re-checks what the package actually delivers against these same ids.
671
+ *
672
+ * What it does NOT refuse, deliberately: an augmentation that is discovered and NOT opted in. That is the
673
+ * ordinary state of a provider package augmenting many refs, and it contributes nothing.
674
+ *
675
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — admitting third-party operations to a provider's
676
+ * grant is checked against the application's explicit opt-in before any artifact records it.
677
+ */
678
+ function validateProviderAugmentationOptIns(input) {
679
+ const { errors, saasConfig, discoveredContributions, discoveredAugmentations } = input;
680
+ const optIns = saasConfig.providers?.augmentations ?? {};
681
+ const scopes = saasConfig.providers?.scopes ?? {};
682
+ const scopedRefs = new Set([
683
+ ...Object.keys(scopes.backend?.providers ?? {}),
684
+ ...Object.keys(scopes.companion?.providers ?? {}),
685
+ ...Object.values(scopes.frontendServices ?? {}).flatMap((scope) => Object.keys(scope.providers ?? {})),
686
+ ...Object.values(scopes.minions ?? {}).flatMap((scope) => Object.keys(scope.providers ?? {})),
687
+ ...Object.values(scopes.workers ?? {}).flatMap((scope) => Object.keys(scope.providers ?? {})),
688
+ ]);
689
+ for (const [baseRef, packageNames] of Object.entries(optIns).sort(([left], [right]) => left.localeCompare(right))) {
690
+ if (!scopedRefs.has(baseRef)) {
691
+ errors.push(`providers.augmentations names "${baseRef}", which no providers.scopes entry declares. An augmentation adds `
692
+ + 'operations to a provider the application uses; scope the provider first.');
693
+ continue;
694
+ }
695
+ const baseContributions = discoveredContributions.filter((contribution) => contribution.ref === baseRef);
696
+ const baseRunsRest = baseContributions.some((contribution) => contribution.protocols.includes(BUILTIN_PROVIDER_PROTOCOL.REST_API));
697
+ if (baseContributions.length > 0 && !baseRunsRest) {
698
+ errors.push(`providers.augmentations opts ${packageNames.map((name) => `"${name}"`).join(', ')} into "${baseRef}", which `
699
+ + `declares no ${BUILTIN_PROVIDER_PROTOCOL.REST_API} binding. An augmentation's operations run through the base `
700
+ + 'provider\'s REST contract — its base URL and credential — so a provider without one cannot be augmented.');
701
+ }
702
+ const declaredBy = new Map();
703
+ for (const packageName of packageNames) {
704
+ const fromPackage = discoveredAugmentations.filter((augmentation) => augmentation.packageName === packageName
705
+ || augmentation.owner.key === packageName);
706
+ if (fromPackage.length === 0) {
707
+ errors.push(describeUndiscoveredAugmentationPackage(packageName, baseRef));
708
+ continue;
709
+ }
710
+ const ofThisRef = fromPackage.filter((candidate) => candidate.augments === baseRef);
711
+ if (ofThisRef.length > 1) {
712
+ errors.push(`"${packageName}" declares ${ofThisRef.length} augmentations of "${baseRef}". A package augments a provider once; `
713
+ + 'merge them into one record so the operation set the application opts into is one list.');
714
+ continue;
715
+ }
716
+ const augmentation = ofThisRef[0];
717
+ if (augmentation === undefined) {
718
+ const augmented = [...new Set(fromPackage.map((candidate) => candidate.augments))].sort();
719
+ errors.push(`providers.augmentations opts "${packageName}" into "${baseRef}", but that package augments `
720
+ + `${augmented.map((ref) => `"${ref}"`).join(', ')} and not "${baseRef}".`);
721
+ continue;
722
+ }
723
+ if (augmentation.packageName !== augmentation.owner.key && augmentation.owner.kind === ProviderContributionOwnerKind.PROVIDER_PACKAGE) {
724
+ errors.push(`The augmentation of "${baseRef}" found in package "${augmentation.owner.key}" names itself "${augmentation.packageName}". `
725
+ + 'An augmentation\'s packageName must be its own manifest name — it is what the audit trail attributes calls to.');
726
+ continue;
727
+ }
728
+ if (augmentation.packageVersion === undefined) {
729
+ errors.push(`"${packageName}" (augmenting "${baseRef}") states no version in its package.json; the audit trail records it beside every call it contributes.`);
730
+ }
731
+ const base = baseContributions.find((contribution) => contribution.protocols.includes(BUILTIN_PROVIDER_PROTOCOL.REST_API));
732
+ const baseVersionRefusal = base === undefined ? undefined : describeAugmentationBaseVersionRefusal(augmentation, base);
733
+ if (baseVersionRefusal !== undefined)
734
+ errors.push(baseVersionRefusal);
735
+ for (const key of Object.keys(augmentation)) {
736
+ const owned = BASE_OWNED_AUGMENTATION_RECORD_KEYS[key];
737
+ if (owned !== undefined) {
738
+ errors.push(`"${packageName}" declares \`${key}\` in its augmentation of "${baseRef}", which would change ${owned} — only `
739
+ + 'the provider\'s owner declares that; an augmentation adds operations only.');
740
+ }
741
+ }
742
+ for (const operationId of augmentation.operationIds) {
743
+ const earlier = declaredBy.get(operationId);
744
+ if (earlier !== undefined) {
745
+ errors.push(`"${earlier}" and "${packageName}" both add operation '${operationId}' to "${baseRef}". An operation id names `
746
+ + 'one request; opt in only one of them.');
747
+ }
748
+ declaredBy.set(operationId, packageName);
749
+ }
750
+ }
751
+ }
752
+ }
753
+ /**
754
+ * The package that ships a base provider, and its installed version when the walk read that package itself (#1672,
755
+ * #1731). The version is `undefined` for a base an application's own runtime package contributes, which has no
756
+ * installed version to hold an augmentation to.
757
+ */
758
+ export function resolveProviderBasePackage(base) {
759
+ const importPath = base.runtimeImportPath;
760
+ const basePackageName = importPath.startsWith('@') ? importPath.split('/').slice(0, 2).join('/') : importPath.split('/')[0];
761
+ const basePackageVersion = base.owner.kind === ProviderContributionOwnerKind.PROVIDER_PACKAGE && base.owner.key === basePackageName
762
+ ? readPackageVersion(base.owner.packageRoot)
763
+ : undefined;
764
+ return { basePackageName, ...(basePackageVersion === undefined ? {} : { basePackageVersion }) };
765
+ }
766
+ /**
767
+ * The refusal, if any, of an opted-in augmentation whose peer range on its base's package does not admit the
768
+ * installed base (#1731).
769
+ *
770
+ * An augmentation's operations run on the base provider's base URL, credential and operation-id namespace, all of
771
+ * which move with the package that ships the base — for an engine ref, the engine. So the augmenting package states
772
+ * the base versions it was written against the way npm states any such requirement: a `peerDependencies` range on
773
+ * that package. Versioning stays at publication; there is no in-code compatibility table.
774
+ *
775
+ * - A range the installed version does not satisfy is refused, naming the augmentation, the range and the version.
776
+ * - A MISSING range is refused too: an augmentation that says nothing about its base cannot be held to one, and an
777
+ * engine upgrade would break it with nothing reporting it — the very failure this exists to catch.
778
+ * - A range this reader cannot parse is refused rather than guessed.
779
+ * - A `workspace:` range is admitted: inside one workspace the peer IS the linked base, whatever its version.
780
+ * - A base with no installed version (an application's own runtime package) cannot be checked, and is not.
781
+ *
782
+ * assurance-control: WILDO.SECURITY.FAIL_CLOSED — third-party operations reach a provider's grant only when the
783
+ * package declares, and the installed base satisfies, the base version it was written against.
784
+ */
785
+ function describeAugmentationBaseVersionRefusal(augmentation, base) {
786
+ const { basePackageName, basePackageVersion } = resolveProviderBasePackage(base);
787
+ if (basePackageVersion === undefined)
788
+ return undefined;
789
+ if (augmentation.owner.kind !== ProviderContributionOwnerKind.PROVIDER_PACKAGE || augmentation.owner.key === basePackageName)
790
+ return undefined;
791
+ const subject = `"${augmentation.packageName}" (augmenting "${augmentation.augments}")`;
792
+ const range = readPeerDependencyRange(augmentation.owner.packageRoot, basePackageName);
793
+ if (range === undefined) {
794
+ return `${subject} declares no peerDependencies range on "${basePackageName}", the package that ships its base (installed `
795
+ + `${basePackageVersion}). An augmentation states the base versions it was written against as a peer range, so an `
796
+ + 'upgrade of the base cannot break it silently; add one to its package.json.';
797
+ }
798
+ if (range.startsWith('workspace:'))
799
+ return undefined;
800
+ const satisfied = satisfiesNpmVersionRange(basePackageVersion, range);
801
+ if (satisfied === true)
802
+ return undefined;
803
+ if (satisfied === undefined) {
804
+ return `${subject} declares the peer range "${range}" on "${basePackageName}", which cannot be read as an npm version range.`;
805
+ }
806
+ return `${subject} requires "${basePackageName}" ${range}, and ${basePackageVersion} is installed. Upgrade the augmenting `
807
+ + `package to a version written against ${basePackageVersion}, or remove it from providers.augmentations.`;
808
+ }
809
+ /** The `peerDependencies` range a package's manifest states for `dependencyName`, or `undefined`. */
810
+ function readPeerDependencyRange(packageRoot, dependencyName) {
811
+ try {
812
+ const manifest = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
813
+ const range = manifest.peerDependencies?.[dependencyName];
814
+ return typeof range === 'string' ? range : undefined;
815
+ }
816
+ catch {
817
+ return undefined;
818
+ }
819
+ }
820
+ /**
821
+ * Why an opted-in package was not found, pointing at the right remedy: a package outside `@wildo-ai` and the
822
+ * application's own scope is walked only when `providers.packages` lists it (#1676), while an own-scope package is
823
+ * walked under the `<scope>/provider-` naming convention (or by being listed too).
824
+ */
825
+ function describeUndiscoveredAugmentationPackage(packageName, baseRef) {
826
+ const scope = packageName.startsWith('@') ? packageName.split('/')[0] : undefined;
827
+ const prefix = `providers.augmentations opts "${packageName}" into "${baseRef}", but discovery found no augmentation from that package.`;
828
+ if (scope === undefined || scope === '@wildo-ai') {
829
+ return `${prefix} Check that it is a dependency of a runtime owner, is installed, and exports \`providerAugmentations\` from its \`./companion\` door.`;
830
+ }
831
+ return `${prefix} Discovery walks \`@wildo-ai/provider-*\`, the engine barrel and packages named `
832
+ + `\`<application-scope>/provider-*\` by themselves; any other package is walked only when \`providers.packages\` lists it. `
833
+ + `List "${packageName}" there, and make it a dependency of a runtime owner.`;
834
+ }
297
835
  /**
298
836
  * The part of a refusal that says the walk was INCOMPLETE, or nothing when it was not.
299
837
  *
@@ -399,15 +937,27 @@ function resolveContributionTargets(saasRoot, saasConfig) {
399
937
  * here would make `wildo config sync` unrunnable in exactly the state where an operator runs it to
400
938
  * find out what is wrong.
401
939
  */
402
- function resolveProviderPackageTargets(saasRoot, runtimeOwnerPackageRoots) {
940
+ function resolveProviderPackageTargets(saasRoot, runtimeOwnerPackageRoots, listedPackageNames) {
403
941
  const prefixes = resolveProviderPackagePrefixes(saasRoot);
404
942
  const searchRoots = [saasRoot, ...runtimeOwnerPackageRoots];
943
+ const listed = new Set(listedPackageNames);
944
+ const admittedByName = (dependencyName) => dependencyName === FRAMEWORK_ENGINE_PROVIDER_PACKAGE
945
+ || dependencyName === FRAMEWORK_SYSTEMS_OF_RECORD_PACKAGE
946
+ || prefixes.some((prefix) => dependencyName.startsWith(prefix));
947
+ // A search root's OWN name is in the set `readRuntimeReachablePackageNames` answers, and is never a dependency.
948
+ const ownPackageNames = new Set(searchRoots.map((root) => readPackageName(root)).filter((name) => name !== undefined));
405
949
  const candidateNames = new Set();
950
+ const dependencyNames = new Set();
406
951
  for (const searchRoot of searchRoots) {
407
952
  for (const dependencyName of readRuntimeReachablePackageNames(searchRoot)) {
408
- if (dependencyName === FRAMEWORK_PROVIDER_CATALOGUE_PACKAGE
409
- || dependencyName === FRAMEWORK_ENGINE_PROVIDER_PACKAGE
410
- || prefixes.some((prefix) => dependencyName.startsWith(prefix))) {
953
+ dependencyNames.add(dependencyName);
954
+ /*
955
+ * assurance-control: WILDO.SECURITY.FAIL_CLOSED — a dependency is EXECUTED by this walk only when it carries a
956
+ * framework name, the application's own `<scope>/provider-*` name, or the application LISTS it in `providers.packages` (#1676).
957
+ * Installing a package from somebody else's scope admits nothing; the listing is reviewable in
958
+ * `wildo.saas.config.ts`, and every admitted package is printed by `config sync` and recorded in the lock.
959
+ */
960
+ if (admittedByName(dependencyName) || (listed.has(dependencyName) && !ownPackageNames.has(dependencyName))) {
411
961
  candidateNames.add(dependencyName);
412
962
  }
413
963
  }
@@ -425,7 +975,82 @@ function resolveProviderPackageTargets(saasRoot, runtimeOwnerPackageRoots) {
425
975
  packageRoot,
426
976
  });
427
977
  }
428
- return [...targetsByRoot.values()];
978
+ return { targets: [...targetsByRoot.values()], dependencyNames, ownPackageNames, admittedByName };
979
+ }
980
+ /**
981
+ * The refusal for an application that declares system-of-record instances and whose walk did not record the framework
982
+ * library's facet module (#2013) — the library is declared but not installed, or not declared at all.
983
+ *
984
+ * Refused here, at sync, because the alternative is worse and later: an artifact without the library's module boots a
985
+ * backend that refuses every instance whose vendor only the library describes (`VENDOR_HAS_NO_FACET`), and `wildo
986
+ * secrets` cannot list those instances' credential slots. The remedy needs no running process: `wildo config sync`
987
+ * declares the library on the backend service and links it (`declareSystemsOfRecordLibrary` in the CLI), and a
988
+ * `pnpm install` installs it.
989
+ */
990
+ function describeUndiscoveredSystemsOfRecordLibrary(systemsOfRecord, facetModules) {
991
+ const instances = Object.keys(systemsOfRecord);
992
+ if (instances.length === 0)
993
+ return [];
994
+ if (facetModules.includes(`${FRAMEWORK_SYSTEMS_OF_RECORD_PACKAGE}${SYSTEM_OF_RECORD_FACET_SUBPATH.slice(1)}`))
995
+ return [];
996
+ return [
997
+ `systemsOfRecord declares ${instances.map((name) => `"${name}"`).join(', ')}, and ${FRAMEWORK_SYSTEMS_OF_RECORD_PACKAGE} — the vendor `
998
+ + 'facets every instance reads — was not discovered. `wildo config sync` declares it on the backend service; run your package '
999
+ + "manager's install (pnpm install), then run `wildo config sync` again.",
1000
+ ];
1001
+ }
1002
+ /**
1003
+ * One refusal per package an instance opts into (`facetAugmentations`) whose facet module the walk did not record
1004
+ * (#1675) — the sentence the backend's resolver refuses the boot with, said at sync instead.
1005
+ */
1006
+ function describeUndiscoveredFacetAugmentationPackages(systemsOfRecord, facetModules) {
1007
+ const recordedPackages = new Set(facetModules.map((specifier) => (specifier.endsWith(SYSTEM_OF_RECORD_FACET_SUBPATH.slice(1))
1008
+ ? specifier.slice(0, -SYSTEM_OF_RECORD_FACET_SUBPATH.slice(1).length)
1009
+ : specifier)));
1010
+ const refusals = [];
1011
+ for (const [name, declaration] of Object.entries(systemsOfRecord)) {
1012
+ for (const packageName of declaration.facetAugmentations ?? []) {
1013
+ if (!recordedPackages.has(packageName)) {
1014
+ refusals.push(`systemsOfRecord.${name}.facetAugmentations names ${packageName}: ${SYSTEM_OF_RECORD_FACET_MODULE_NOT_DISCOVERED}.`);
1015
+ }
1016
+ }
1017
+ }
1018
+ return refusals;
1019
+ }
1020
+ /** One refusal per listed package discovery could not admit (#1676), each naming the package and the remedy. */
1021
+ function describeRefusedProviderPackageListings(listed) {
1022
+ const refusals = [];
1023
+ for (const entry of listed) {
1024
+ const subject = `providers.packages lists "${entry.packageName}"`;
1025
+ switch (entry.status) {
1026
+ case ProviderPackageListingStatus.ADMITTED:
1027
+ break;
1028
+ case ProviderPackageListingStatus.NOT_A_DEPENDENCY:
1029
+ refusals.push(`${subject}, but neither the application root nor any runtime owner depends on it — add it to the `
1030
+ + 'package.json of the runtime that uses it (usually backend-api), or remove the listing.');
1031
+ break;
1032
+ case ProviderPackageListingStatus.NOT_INSTALLED:
1033
+ refusals.push(`${subject}, which is declared as a dependency and is not installed — run your package manager's install.`);
1034
+ break;
1035
+ case ProviderPackageListingStatus.UNREADABLE:
1036
+ refusals.push(`${subject}, whose companion entry could not be read (${entry.reason ?? 'unknown error'}).`);
1037
+ break;
1038
+ case ProviderPackageListingStatus.ALREADY_WALKED:
1039
+ refusals.push(`${subject}, which discovery walks by name already — remove the listing; \`providers.packages\` is for `
1040
+ + 'a package discovery does not walk by itself: one from another scope, or one of the application\'s own scope '
1041
+ + 'not named `<scope>/provider-*`.');
1042
+ break;
1043
+ case ProviderPackageListingStatus.RUNTIME_OWNER:
1044
+ refusals.push(`${subject}, which is one of this application's own runtime packages — it is walked as a runtime owner, `
1045
+ + 'not as a provider package; remove the listing.');
1046
+ break;
1047
+ case ProviderPackageListingStatus.CONTRIBUTES_NOTHING:
1048
+ refusals.push(`${subject}, which ships no provider contribution, no provider augmentation and no ./systems-of-record `
1049
+ + 'module — it is not a provider package, or the wrong package is listed.');
1050
+ break;
1051
+ }
1052
+ }
1053
+ return refusals;
429
1054
  }
430
1055
  /**
431
1056
  * The framework prefix, plus the application's own scope when its root manifest has one.
@@ -488,6 +1113,20 @@ function resolveProviderPackageRoot(packageName, searchRoots) {
488
1113
  }
489
1114
  return undefined;
490
1115
  }
1116
+ /** The installed version a package's own manifest states, or `undefined` when it states none or is unreadable. */
1117
+ export function readPackageVersion(packageRoot) {
1118
+ const packageJsonPath = join(packageRoot, 'package.json');
1119
+ if (!existsSync(packageJsonPath)) {
1120
+ return undefined;
1121
+ }
1122
+ try {
1123
+ const version = JSON.parse(readFileSync(packageJsonPath, 'utf-8')).version;
1124
+ return typeof version === 'string' && version.length > 0 ? version : undefined;
1125
+ }
1126
+ catch {
1127
+ return undefined;
1128
+ }
1129
+ }
491
1130
  function readPackageName(packageRoot) {
492
1131
  const packageJsonPath = join(packageRoot, 'package.json');
493
1132
  if (!existsSync(packageJsonPath)) {
@@ -531,6 +1170,9 @@ function validateRuntimeScopeAgainstDiscovery(input) {
531
1170
  errors.push(`Provider "${providerRef}" is authored in scope "${scopeLabel}" but no companion export contributes it for that runtime.`);
532
1171
  continue;
533
1172
  }
1173
+ const claimedTwice = describeProviderRefClaimedByMoreThanOneImportPath(providerRef, `scope "${scopeLabel}"`, matchingContributions);
1174
+ if (claimedTwice !== undefined)
1175
+ errors.push(claimedTwice);
534
1176
  const discoveredEngineCapabilities = new Set(matchingContributions.flatMap((contribution) => contribution.engineCapabilities));
535
1177
  const discoveredProviderCapabilities = new Set(matchingContributions.flatMap((contribution) => contribution.providerCapabilities));
536
1178
  const discoveredProtocols = new Set(matchingContributions.flatMap((contribution) => contribution.protocols));
@@ -554,6 +1196,43 @@ function validateRuntimeScopeAgainstDiscovery(input) {
554
1196
  }
555
1197
  }
556
1198
  }
1199
+ /**
1200
+ * The refusal for one provider ref claimed, for ONE runtime, through more than one import path (#2014, epic #2012).
1201
+ * `undefined` when the contributions agree.
1202
+ *
1203
+ * A runtime loads one module per ref, from the path its provider artifact records. When two packages contribute
1204
+ * the same ref for the same runtime, that path used to be the alphabetically first — so a second package contributing
1205
+ * a ref the application's own copy (`@<app>/provider-asana`) also contributes decided silently which module loaded.
1206
+ * The case that motivated it (#2014) was a leftover install of the since-archived catalogue, whose `asana` subpath
1207
+ * sorted first; the same holds for any framework `@wildo-ai/provider-<ref>` package installed beside the copy.
1208
+ *
1209
+ * Scoped to one runtime on purpose: the same ref legitimately has one path per FACET — `posthog` is
1210
+ * `@wildo-ai/external-connectors-public/app` for the SaaS frontend and `@wildo-ai/external-connectors-private/backend`
1211
+ * for the backend. Measured 2026-09-29 over Wonder Todos and Wonder CRM: six refs have several paths, and no ref has
1212
+ * two for the same runtime.
1213
+ *
1214
+ * Shared by discovery validation (`wildo config sync`, `wildo lock check`) and the artifact builder, so the two
1215
+ * cannot disagree about what counts as a second claimant.
1216
+ */
1217
+ export function describeProviderRefClaimedByMoreThanOneImportPath(providerRef, runtimeLabel, contributions) {
1218
+ const ownersByPath = new Map();
1219
+ for (const contribution of contributions) {
1220
+ if (contribution.ref !== providerRef)
1221
+ continue;
1222
+ const owners = ownersByPath.get(contribution.runtimeImportPath) ?? new Set();
1223
+ owners.add(`${contribution.owner.kind} "${contribution.owner.key}"`);
1224
+ ownersByPath.set(contribution.runtimeImportPath, owners);
1225
+ }
1226
+ if (ownersByPath.size <= 1)
1227
+ return undefined;
1228
+ const claims = [...ownersByPath]
1229
+ .sort(([left], [right]) => left.localeCompare(right))
1230
+ .map(([path, owners]) => `"${path}" (reached through ${[...owners].sort().join(', ')})`)
1231
+ .join(' and ');
1232
+ return `Provider "${providerRef}" is claimed for ${runtimeLabel} through more than one import path: ${claims}. `
1233
+ + 'A runtime loads one module per ref, so it cannot pick one. Keep one: uninstall the package that should not '
1234
+ + 'provide it, or remove its dependency from that runtime.';
1235
+ }
557
1236
  function describeContribution(contribution) {
558
1237
  return `Provider contribution "${contribution.ref}" from ${contribution.owner.kind} "${contribution.owner.key}"`;
559
1238
  }