@xemahq/kernel-contracts 0.22.1 → 0.22.3

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/dist/agent-workspace/awp-spec.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://xema.dev/schemas/awp-spec.v1.json",
-  "emittedAt": "2026-07-01T10:43:39.744Z",
+  "emittedAt": "2026-07-02T07:22:41.877Z",
   "spec": {
     "id": "awp/v1",
     "version": "1.2.0",

package/dist/connector/index.d.ts

@@ -2,6 +2,8 @@ export * from './lib/adapter-kind';
 export * from './lib/capability';
 export * from './lib/credential-kind';
 export * from './lib/onboarding-manifest';
+export * from './lib/provider-descriptor';
+export * from './lib/connector-descriptor';
 export * from './lib/envelope-schema';
 export * from './lib/filter-expr';
 export * from './lib/filter-expr-schema';

package/dist/connector/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}

package/dist/connector/index.js

@@ -18,6 +18,8 @@ __exportStar(require("./lib/adapter-kind"), exports);
 __exportStar(require("./lib/capability"), exports);
 __exportStar(require("./lib/credential-kind"), exports);
 __exportStar(require("./lib/onboarding-manifest"), exports);
+__exportStar(require("./lib/provider-descriptor"), exports);
+__exportStar(require("./lib/connector-descriptor"), exports);
 __exportStar(require("./lib/envelope-schema"), exports);
 __exportStar(require("./lib/filter-expr"), exports);
 __exportStar(require("./lib/filter-expr-schema"), exports);

package/dist/connector/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,mDAAiC;AACjC,wDAAsC;AACtC,4DAA0C;AAC1C,wDAAsC;AACtC,oDAAkC;AAClC,2DAAyC;AACzC,6DAA2C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,mDAAiC;AACjC,wDAAsC;AACtC,4DAA0C;AAC1C,4DAA0C;AAC1C,6DAA2C;AAC3C,wDAAsC;AACtC,oDAAkC;AAClC,2DAAyC;AACzC,6DAA2C"}

package/dist/connector/lib/connector-descriptor.d.ts

@@ -0,0 +1,13 @@
+import type { AdapterKindRef } from './adapter-kind';
+import type { CredentialKind } from './credential-kind';
+export interface ConnectorDescriptor {
+    readonly connectorKey: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly iconName: string;
+    readonly providerKey: string;
+    readonly scopes: readonly string[];
+    readonly connectionCredentialKind: CredentialKind;
+    readonly adapterKind: AdapterKindRef;
+}
+//# sourceMappingURL=connector-descriptor.d.ts.map

package/dist/connector/lib/connector-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-descriptor.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AASxD,MAAM,WAAW,mBAAmB;IAElC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAU7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAOnC,QAAQ,CAAC,wBAAwB,EAAE,cAAc,CAAC;IAOlD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;CACtC"}

package/dist/connector/lib/connector-descriptor.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=connector-descriptor.js.map

package/dist/connector/lib/connector-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-descriptor.js","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":""}

package/dist/connector/lib/provider-descriptor.d.ts

@@ -0,0 +1,37 @@
+import type { CredentialFieldSpec } from './onboarding-manifest';
+export declare enum ProviderAppAuthKind {
+    OAuth2 = "oauth2",
+    AppInstall = "app_install",
+    None = "none"
+}
+export declare enum ProviderOrigin {
+    Kernel = "kernel",
+    Platform = "platform",
+    Biome = "biome"
+}
+export declare enum ProviderCredentialScope {
+    Platform = "platform",
+    Org = "org"
+}
+export declare const PROVIDER_CREDENTIAL_SCOPE_ORDER: readonly ProviderCredentialScope[];
+export interface ProviderOAuthEndpoints {
+    readonly authorizationUrl: string;
+    readonly tokenUrl: string;
+    readonly extraAuthorizeParams?: Readonly<Record<string, string>>;
+    readonly clientIdEnvVar?: string;
+    readonly clientSecretEnvVar?: string;
+}
+export interface ProviderDescriptor {
+    readonly providerKey: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly iconName: string;
+    readonly category: string;
+    readonly appAuthKind: ProviderAppAuthKind;
+    readonly origin: ProviderOrigin;
+    readonly appCredentialSchema?: readonly CredentialFieldSpec[];
+    readonly oauthEndpoints?: ProviderOAuthEndpoints;
+    readonly allowOrgOverride: boolean;
+}
+export declare function providerRequiresAppCredential(provider: Pick<ProviderDescriptor, 'appAuthKind'>): boolean;
+//# sourceMappingURL=provider-descriptor.d.ts.map

package/dist/connector/lib/provider-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-descriptor.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/provider-descriptor.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAQjE,oBAAY,mBAAmB;IAO7B,MAAM,WAAW;IAMjB,UAAU,gBAAgB;IAO1B,IAAI,SAAS;CACd;AAaD,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,KAAK,UAAU;CAChB;AAiBD,oBAAY,uBAAuB;IACjC,QAAQ,aAAa;IACrB,GAAG,QAAQ;CACZ;AAGD,eAAO,MAAM,+BAA+B,EAAE,SAAS,uBAAuB,EACb,CAAC;AAOlE,MAAM,WAAW,sBAAsB;IAErC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAQ1B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAQjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAOD,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAE1C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAQhC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAM9D,QAAQ,CAAC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IAOjD,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAOD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,GAChD,OAAO,CAET"}

package/dist/connector/lib/provider-descriptor.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_CREDENTIAL_SCOPE_ORDER = exports.ProviderCredentialScope = exports.ProviderOrigin = exports.ProviderAppAuthKind = void 0;
+exports.providerRequiresAppCredential = providerRequiresAppCredential;
+var ProviderAppAuthKind;
+(function (ProviderAppAuthKind) {
+    ProviderAppAuthKind["OAuth2"] = "oauth2";
+    ProviderAppAuthKind["AppInstall"] = "app_install";
+    ProviderAppAuthKind["None"] = "none";
+})(ProviderAppAuthKind || (exports.ProviderAppAuthKind = ProviderAppAuthKind = {}));
+var ProviderOrigin;
+(function (ProviderOrigin) {
+    ProviderOrigin["Kernel"] = "kernel";
+    ProviderOrigin["Platform"] = "platform";
+    ProviderOrigin["Biome"] = "biome";
+})(ProviderOrigin || (exports.ProviderOrigin = ProviderOrigin = {}));
+var ProviderCredentialScope;
+(function (ProviderCredentialScope) {
+    ProviderCredentialScope["Platform"] = "platform";
+    ProviderCredentialScope["Org"] = "org";
+})(ProviderCredentialScope || (exports.ProviderCredentialScope = ProviderCredentialScope = {}));
+exports.PROVIDER_CREDENTIAL_SCOPE_ORDER = [ProviderCredentialScope.Org, ProviderCredentialScope.Platform];
+function providerRequiresAppCredential(provider) {
+    return provider.appAuthKind !== ProviderAppAuthKind.None;
+}
+//# sourceMappingURL=provider-descriptor.js.map

package/dist/connector/lib/provider-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-descriptor.js","sourceRoot":"","sources":["../../../src/connector/lib/provider-descriptor.ts"],"names":[],"mappings":";;;AAgLA,sEAIC;AAlJD,IAAY,mBAqBX;AArBD,WAAY,mBAAmB;IAO7B,wCAAiB,CAAA;IAMjB,iDAA0B,CAAA;IAO1B,oCAAa,CAAA;AACf,CAAC,EArBW,mBAAmB,mCAAnB,mBAAmB,QAqB9B;AAaD,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,uCAAqB,CAAA;IACrB,iCAAe,CAAA;AACjB,CAAC,EAJW,cAAc,8BAAd,cAAc,QAIzB;AAiBD,IAAY,uBAGX;AAHD,WAAY,uBAAuB;IACjC,gDAAqB,CAAA;IACrB,sCAAW,CAAA;AACb,CAAC,EAHW,uBAAuB,uCAAvB,uBAAuB,QAGlC;AAGY,QAAA,+BAA+B,GAC1C,CAAC,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;AAgFlE,SAAgB,6BAA6B,CAC3C,QAAiD;IAEjD,OAAO,QAAQ,CAAC,WAAW,KAAK,mBAAmB,CAAC,IAAI,CAAC;AAC3D,CAAC"}

package/dist/policy/lib/policy.d.ts

@@ -12,7 +12,8 @@ export declare enum CredentialPrecedenceSource {
     Explicit = "explicit",
     CapabilityDefault = "capability_default",
     ProjectDefault = "project_default",
-    OrgDefault = "org_default"
+    OrgDefault = "org_default",
+    PlatformDefault = "platform_default"
 }
 export declare const CredentialPrecedenceSourceSchema: z.ZodEnum<typeof CredentialPrecedenceSource>;
 export type PolicyRequest = ExecutionContext;

package/dist/policy/lib/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAShE,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,aAAa,mBAAmB;CACjC;AAED,eAAO,MAAM,wBAAwB,sCAAmC,CAAC;AAczE,oBAAY,0BAA0B;IACpC,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,cAAc,oBAAoB;IAClC,UAAU,gBAAgB;CAC3B;AAED,eAAO,MAAM,gCAAgC,8CAE5C,CAAC;AAWF,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE7C,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CACjC,CAAC;AAWzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,SAAS,CAAC;IAWvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAM7B,2BAA2B,CAAC,EAAE,0BAA0B,CAAC;CAC1D;AAED,eAAO,MAAM,oBAAoB,EAO3B,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAShE,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,aAAa,mBAAmB;CACjC;AAED,eAAO,MAAM,wBAAwB,sCAAmC,CAAC;AAgBzE,oBAAY,0BAA0B;IACpC,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,cAAc,oBAAoB;IAClC,UAAU,gBAAgB;IAO1B,eAAe,qBAAqB;CACrC;AAED,eAAO,MAAM,gCAAgC,8CAE5C,CAAC;AAWF,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE7C,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CACjC,CAAC;AAWzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,SAAS,CAAC;IAWvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAM7B,2BAA2B,CAAC,EAAE,0BAA0B,CAAC;CAC1D;AAED,eAAO,MAAM,oBAAoB,EAO3B,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC"}

package/dist/policy/lib/policy.js

@@ -18,6 +18,7 @@ var CredentialPrecedenceSource;
     CredentialPrecedenceSource["CapabilityDefault"] = "capability_default";
     CredentialPrecedenceSource["ProjectDefault"] = "project_default";
     CredentialPrecedenceSource["OrgDefault"] = "org_default";
+    CredentialPrecedenceSource["PlatformDefault"] = "platform_default";
 })(CredentialPrecedenceSource || (exports.CredentialPrecedenceSource = CredentialPrecedenceSource = {}));
 exports.CredentialPrecedenceSourceSchema = zod_1.z.nativeEnum(CredentialPrecedenceSource);
 exports.PolicyRequestSchema = execution_context_1.ExecutionContextSchema;

package/dist/policy/lib/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,+DAGiC;AACjC,+CAGuB;AACvB,+CAAgE;AAShE,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;IACf,mCAAa,CAAA;IACb,sDAAgC,CAAA;AAClC,CAAC,EAJW,kBAAkB,kCAAlB,kBAAkB,QAI7B;AAEY,QAAA,wBAAwB,GAAG,OAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAczE,IAAY,0BAKX;AALD,WAAY,0BAA0B;IACpC,mDAAqB,CAAA;IACrB,sEAAwC,CAAA;IACxC,gEAAkC,CAAA;IAClC,wDAA0B,CAAA;AAC5B,CAAC,EALW,0BAA0B,0CAA1B,0BAA0B,QAKrC;AAEY,QAAA,gCAAgC,GAAG,OAAC,CAAC,UAAU,CAC1D,0BAA0B,CAC3B,CAAC;AAaW,QAAA,mBAAmB,GAC9B,0CAAsB,CAAC;AAmCZ,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,gCAAwB;IAC9B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,KAAK,CAAC,oCAAsB,CAAC,CAAC,QAAQ,EAAE;IACvD,UAAU,EAAE,6BAAe,CAAC,QAAQ,EAAE;IACtC,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjD,2BAA2B,EAAE,wCAAgC,CAAC,QAAQ,EAAE;CACzE,CAA8B,CAAC"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,+DAGiC;AACjC,+CAGuB;AACvB,+CAAgE;AAShE,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;IACf,mCAAa,CAAA;IACb,sDAAgC,CAAA;AAClC,CAAC,EAJW,kBAAkB,kCAAlB,kBAAkB,QAI7B;AAEY,QAAA,wBAAwB,GAAG,OAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAgBzE,IAAY,0BAYX;AAZD,WAAY,0BAA0B;IACpC,mDAAqB,CAAA;IACrB,sEAAwC,CAAA;IACxC,gEAAkC,CAAA;IAClC,wDAA0B,CAAA;IAO1B,kEAAoC,CAAA;AACtC,CAAC,EAZW,0BAA0B,0CAA1B,0BAA0B,QAYrC;AAEY,QAAA,gCAAgC,GAAG,OAAC,CAAC,UAAU,CAC1D,0BAA0B,CAC3B,CAAC;AAaW,QAAA,mBAAmB,GAC9B,0CAAsB,CAAC;AAmCZ,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,gCAAwB;IAC9B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,KAAK,CAAC,oCAAsB,CAAC,CAAC,QAAQ,EAAE;IACvD,UAAU,EAAE,6BAAe,CAAC,QAAQ,EAAE;IACtC,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjD,2BAA2B,EAAE,wCAAgC,CAAC,QAAQ,EAAE;CACzE,CAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 32 kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -10,26 +10,18 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint .",
-    "check:boundary": "node scripts/check-subpath-dag.mjs"
-  },
   "devDependencies": {
-    "@eslint/js": "catalog:",
-    "@types/node": "catalog:",
-    "eslint": "catalog:",
-    "eslint-config-prettier": "catalog:",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "25.2.3",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.31.0",
-    "prettier": "catalog:",
-    "typescript": "catalog:",
-    "typescript-eslint": "catalog:"
+    "prettier": "3.6.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.56.1"
   },
   "dependencies": {
-    "zod": "catalog:"
+    "zod": "^4.3.6"
   },
   "exports": {
     "./*": {
@@ -38,5 +30,13 @@
       "default": "./dist/*/index.js"
     },
     "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "check:boundary": "node scripts/check-subpath-dag.mjs"
   }
-}
+}

package/src/connector/index.ts

@@ -2,6 +2,8 @@ export * from './lib/adapter-kind';
 export * from './lib/capability';
 export * from './lib/credential-kind';
 export * from './lib/onboarding-manifest';
+export * from './lib/provider-descriptor';
+export * from './lib/connector-descriptor';
 export * from './lib/envelope-schema';
 export * from './lib/filter-expr';
 export * from './lib/filter-expr-schema';

package/src/connector/lib/connector-descriptor.ts

@@ -0,0 +1,66 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Connector descriptor — a capability surface authenticated by ONE provider
+ *
+ * A **Connector** is what a user actually connects: Gmail, Google Drive,
+ * generic IMAP, generic SMTP, a GitHub SCM connector. Every connector names
+ * the **Provider** it authenticates against (`providerKey`) and the incremental
+ * OAuth `scopes` it needs from that provider. The catalog groups connectors by
+ * provider so ONE app credential (per `ProviderDescriptor`) backs many
+ * connectors.
+ *
+ * This descriptor is the connector-registry face of an `IntegrationProvider
+ * Module`: the module carries the executable webhook/action/resource handlers;
+ * this descriptor carries the *catalog + connect* metadata the framework needs
+ * to render the provider-grouped catalog, drive consent with the right scopes,
+ * and resolve the right per-connection credential kind.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import type { AdapterKindRef } from './adapter-kind';
+import type { CredentialKind } from './credential-kind';
+
+/**
+ * A connector in the catalog. `connectorKey` aligns with the persisted
+ * `ConnectorKind` wire value (e.g. `GMAIL`, `IMAP_GENERIC`, `SMTP_GENERIC`)
+ * but is typed as a string here to keep the kernel `connector` contract
+ * package free of the persisted `ConnectorKind` enum (which lives in
+ * platform-common's integration-webhooks); the connector-gateway maps the two.
+ */
+export interface ConnectorDescriptor {
+  /** Stable connector key — aligns with the persisted `ConnectorKind`. */
+  readonly connectorKey: string;
+  /** Human-readable name — `Gmail`, `Generic IMAP`. */
+  readonly displayName: string;
+  /** One-sentence description shown on the connector row. */
+  readonly description: string;
+  /** Lucide-react icon name; may differ from the provider's icon. */
+  readonly iconName: string;
+
+  /** The provider (authenticating authority) this connector belongs to. */
+  readonly providerKey: string;
+
+  /**
+   * Incremental OAuth scopes this connector requests from its provider. Empty
+   * for connectors whose provider `appAuthKind` is `None` (IMAP/SMTP). When a
+   * second connector of the same OAuth provider is connected, the consent
+   * driver requests the UNION of already-granted + these scopes (incremental
+   * consent) so one app credential accrues capability without re-consent for
+   * scopes already held.
+   */
+  readonly scopes: readonly string[];
+
+  /**
+   * How an individual connection to THIS connector authenticates at runtime
+   * (the per-connection wallet/token). `oauth_user` for OAuth connectors,
+   * `imap_auth` / `smtp_auth` for the mail wallets, `pat` / `api_key`, …
+   */
+  readonly connectionCredentialKind: CredentialKind;
+
+  /**
+   * The adapter category this connector plugs into (`mail`, `scm`, …). Drives
+   * where normalized inbound envelopes are forwarded and which project-binding
+   * surface the connector appears under.
+   */
+  readonly adapterKind: AdapterKindRef;
+}

package/src/connector/lib/provider-descriptor.ts

@@ -0,0 +1,181 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Provider descriptor — the authenticating authority ("app") behind N connectors
+ *
+ * A **Provider** is the identity/authority a set of connectors authenticates
+ * against — e.g. `google`, `microsoft`, `github`, `slack`, `smtp`, `imap`.
+ * ONE provider owns ONE **app credential** (a Google Cloud OAuth client, a
+ * GitHub App private key, …) and fans out to MANY **connectors** (Gmail,
+ * Google Drive, Google Calendar …), each of which reuses that single app
+ * credential with its own incremental scopes.
+ *
+ * This is the "Google is a world" fix: the catalog lists connectors grouped
+ * under one provider card; the app credential is provided once (by a platform
+ * admin, or overridden per-org as BYO) and every connector under the provider
+ * reuses it. Adding a new Google service later is a new *connector* with new
+ * scopes — never a new credential and never a framework change.
+ *
+ * The descriptor is a **runtime contract** describing how a provider's app
+ * credential is obtained and where it lives. Actual secret VALUES are never
+ * carried here — only the SCHEMA of what an admin must supply
+ * (`appCredentialSchema`) and non-secret OAuth endpoint metadata. Secrets are
+ * held by the credential broker + custody, referenced by env-var name or
+ * custody ref, never inlined.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import type { CredentialFieldSpec } from './onboarding-manifest';
+
+/**
+ * How a provider's APP-level credential authenticates. This is distinct from
+ * a *connector's* per-connection `CredentialKind` (how an individual user/
+ * mailbox connection authenticates) — it describes the shared "app" that the
+ * platform/org registers once.
+ */
+export enum ProviderAppAuthKind {
+  /**
+   * 3-legged OAuth: the app is a registered OAuth client (clientId/secret).
+   * Connecting a connector runs an authorization-code consent redirect using
+   * the app credential + the connector's scopes. e.g. Google, Microsoft,
+   * Slack.
+   */
+  OAuth2 = 'oauth2',
+  /**
+   * App-installation flow (GitHub App / GitLab App / Atlassian Connect): the
+   * app authenticates via an app id + private key and the user installs it
+   * onto their account/org. e.g. GitHub.
+   */
+  AppInstall = 'app_install',
+  /**
+   * No shared app credential at all — every connection carries its own
+   * complete secret (a mailbox host+user+password, a raw API key). The
+   * connector is connectable with NO platform/org setup. e.g. generic SMTP,
+   * generic IMAP.
+   */
+  None = 'none',
+}
+
+/**
+ * Who shipped a provider. Determines WHICH admin fulfils its app-credential
+ * requirement and at which scope the requirement is registered.
+ *
+ *  - `kernel`   — a first-party provider baked into the platform.
+ *  - `platform` — shipped by a platform (Layer-2) service/biome installed
+ *                 platform-wide; platform admin fulfils it.
+ *  - `biome`    — introduced by a biome. When that biome is installed at ORG
+ *                 scope, the requirement is org-scoped (the org admin BYO-fills
+ *                 it) because the platform never shipped the provider.
+ */
+export enum ProviderOrigin {
+  Kernel = 'kernel',
+  Platform = 'platform',
+  Biome = 'biome',
+}
+
+/**
+ * The two scopes at which a provider's APP credential can be provisioned.
+ * Deliberately a SEPARATE, minimal enum from the 5-tier ownership
+ * `ScopeSource` and from the credential-broker's per-connection
+ * `CredentialScopeTier` — app-credential provisioning is a strict 2-tier
+ * concern: a platform-wide default that an org may override.
+ *
+ * Resolution precedence (narrowest wins):
+ *
+ *   Org (BYO)  >  Platform (default)  >  [legacy env-var fallback]  >  unset
+ *
+ * An unset REQUIRED app credential is surfaced to the correct admin and the
+ * connector reports "needs setup" — it never silently falls through to an
+ * unauthenticated request.
+ */
+export enum ProviderCredentialScope {
+  Platform = 'platform',
+  Org = 'org',
+}
+
+/** Precedence order for app-credential resolution — index 0 wins. */
+export const PROVIDER_CREDENTIAL_SCOPE_ORDER: readonly ProviderCredentialScope[] =
+  [ProviderCredentialScope.Org, ProviderCredentialScope.Platform];
+
+/**
+ * Non-secret OAuth endpoint metadata for a `ProviderAppAuthKind.OAuth2`
+ * provider. Client id/secret are NOT here — they are the app credential,
+ * resolved from a provision (or the legacy env fallback) at consent time.
+ */
+export interface ProviderOAuthEndpoints {
+  /** Authorization-code consent endpoint (where the user is redirected). */
+  readonly authorizationUrl: string;
+  /** Token-exchange endpoint (code→token, refresh-token rotation). */
+  readonly tokenUrl: string;
+  /**
+   * Extra authorize-request params a provider needs to actually mint a
+   * refresh token / do incremental consent. Non-secret. e.g. Google needs
+   * `{ access_type: 'offline', include_granted_scopes: 'true', prompt:
+   * 'consent' }`. Kept explicit rather than hardcoded in the driver so a new
+   * OAuth provider is pure data.
+   */
+  readonly extraAuthorizeParams?: Readonly<Record<string, string>>;
+  /**
+   * Legacy env-var NAMES the OAuth driver falls back to for the app
+   * client id / secret when no provision exists yet (bootstrap before the
+   * platform-admin UI is used). Never the secret itself. Optional — a
+   * provider with no env fallback simply reports "needs setup" until an
+   * admin provisions it.
+   */
+  readonly clientIdEnvVar?: string;
+  readonly clientSecretEnvVar?: string;
+}
+
+/**
+ * A first-class Provider (authenticating authority). Registered in the
+ * provider registry alongside — but distinct from — the connectors that
+ * reference it via `Connector.providerKey`.
+ */
+export interface ProviderDescriptor {
+  /** Stable lowercase slug — `google`, `microsoft`, `github`, `smtp`. */
+  readonly providerKey: string;
+  /** Human-readable name — `Google`, `Microsoft`, `Generic SMTP`. */
+  readonly displayName: string;
+  /** One-sentence description shown on the provider card. */
+  readonly description: string;
+  /** Lucide-react icon name; frontend maps to a component. */
+  readonly iconName: string;
+  /** Catalog grouping label (e.g. `Email`, `Source control`, `Chat`). */
+  readonly category: string;
+
+  /** How the shared app credential authenticates. */
+  readonly appAuthKind: ProviderAppAuthKind;
+  /** Who shipped the provider — drives requirement scope + which admin fills. */
+  readonly origin: ProviderOrigin;
+
+  /**
+   * Schema of the app-credential fields an admin must supply to register the
+   * app (Google → clientId/clientSecret[/pubsubTopic]; GitHub App → appId/
+   * privateKey/webhookSecret). Empty/omitted when `appAuthKind = None`
+   * (nothing to provision — the connector is immediately connectable).
+   */
+  readonly appCredentialSchema?: readonly CredentialFieldSpec[];
+
+  /**
+   * OAuth endpoint metadata — REQUIRED when `appAuthKind = OAuth2`, absent
+   * otherwise.
+   */
+  readonly oauthEndpoints?: ProviderOAuthEndpoints;
+
+  /**
+   * Whether an org may override the platform-default app credential with its
+   * own (BYO app). `false` pins the provider to the platform provision only.
+   * Ignored when `appAuthKind = None` (there is no shared app to override).
+   */
+  readonly allowOrgOverride: boolean;
+}
+
+/**
+ * True when a provider needs an app credential provisioned before any of its
+ * connectors can be connected (i.e. anything other than `None`). Callers use
+ * this to decide whether to surface a "needs setup" state and to whom.
+ */
+export function providerRequiresAppCredential(
+  provider: Pick<ProviderDescriptor, 'appAuthKind'>,
+): boolean {
+  return provider.appAuthKind !== ProviderAppAuthKind.None;
+}

package/src/policy/lib/policy.ts

@@ -33,14 +33,23 @@ export const PolicyDecisionKindSchema = z.nativeEnum(PolicyDecisionKind);
  * Priority, highest wins:
  *   `explicit` (a grant names the binding) > `capability_default`
  *   (the descriptor's `defaultCredentialBindingRef`) > `project_default` >
- *   `org_default`. No match ⇒ the PDP emits NO binding and denies with
- *   `MISSING_CREDENTIAL_BINDING` (never a silent fallback).
+ *   `org_default` > `platform_default` (a deployment-wide default an org may
+ *   override — the Provider–Credential framework's platform tier). No match ⇒
+ *   the PDP emits NO binding and denies with `MISSING_CREDENTIAL_BINDING`
+ *   (never a silent fallback).
  */
 export enum CredentialPrecedenceSource {
   Explicit = 'explicit',
   CapabilityDefault = 'capability_default',
   ProjectDefault = 'project_default',
   OrgDefault = 'org_default',
+  /**
+   * A deployment-wide platform default provision (broadest tier, below org).
+   * An org-scoped default always overrides it. Used by `authorization-api`'s
+   * credential-precedence resolver once this kernel change is published +
+   * consumed (see the Connections framework plan).
+   */
+  PlatformDefault = 'platform_default',
 }
 
 export const CredentialPrecedenceSourceSchema = z.nativeEnum(