@xemahq/kernel-contracts 0.27.0 → 0.28.0

package/dist/capability/index.d.ts

@@ -1,4 +1,5 @@
 export * from './lib/capability-ref';
+export * from './lib/connector-capability-ref';
 export * from './lib/capability-grant';
 export * from './lib/capability-policy';
 export * from './lib/permission-profile';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capability/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iBAAiB,CAAC;AAChC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capability/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iBAAiB,CAAC;AAChC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC"}

package/dist/capability/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./lib/capability-ref"), exports);
+__exportStar(require("./lib/connector-capability-ref"), exports);
 __exportStar(require("./lib/capability-grant"), exports);
 __exportStar(require("./lib/capability-policy"), exports);
 __exportStar(require("./lib/permission-profile"), exports);

package/dist/capability/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capability/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,yDAAuC;AACvC,0DAAwC;AACxC,2DAAyC;AACzC,iEAA+C;AAC/C,kDAAgC;AAChC,gEAA8C;AAC9C,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capability/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,iEAA+C;AAC/C,yDAAuC;AACvC,0DAAwC;AACxC,2DAAyC;AACzC,iEAA+C;AAC/C,kDAAgC;AAChC,gEAA8C;AAC9C,+CAA6B"}

package/dist/capability/lib/connector-capability-ref.d.ts

@@ -0,0 +1,11 @@
+import { type CapabilityRef } from './capability-ref';
+export declare const CONNECTOR_CAPABILITY_DOMAIN = "connector";
+export interface ParsedConnectorCapabilityRef {
+    readonly provider: string;
+    readonly verb: string;
+    readonly major: number;
+    readonly raw: CapabilityRef;
+}
+export declare function buildConnectorCapabilityRef(providerSlug: string, verb: string, major?: number): CapabilityRef;
+export declare function parseConnectorCapabilityRef(ref: string): ParsedConnectorCapabilityRef;
+//# sourceMappingURL=connector-capability-ref.d.ts.map

package/dist/capability/lib/connector-capability-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-capability-ref.d.ts","sourceRoot":"","sources":["../../../src/capability/lib/connector-capability-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,kBAAkB,CAAC;AAkB1B,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAOvD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAiBD,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAI,GACR,aAAa,CAaf;AAeD,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,GACV,4BAA4B,CAoB9B"}

package/dist/capability/lib/connector-capability-ref.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECTOR_CAPABILITY_DOMAIN = void 0;
+exports.buildConnectorCapabilityRef = buildConnectorCapabilityRef;
+exports.parseConnectorCapabilityRef = parseConnectorCapabilityRef;
+const capability_ref_1 = require("./capability-ref");
+const errors_1 = require("./errors");
+exports.CONNECTOR_CAPABILITY_DOMAIN = 'connector';
+function buildConnectorCapabilityRef(providerSlug, verb, major = 1) {
+    const raw = (0, capability_ref_1.formatCapabilityRef)({
+        domain: exports.CONNECTOR_CAPABILITY_DOMAIN,
+        verbPath: [providerSlug, verb],
+        major,
+    });
+    parseConnectorCapabilityRef(raw);
+    return raw;
+}
+function parseConnectorCapabilityRef(ref) {
+    const parsed = (0, capability_ref_1.parseCapabilityRef)(ref);
+    if (parsed.domain !== exports.CONNECTOR_CAPABILITY_DOMAIN) {
+        throw new errors_1.CapabilityRefParseError({
+            message: `Connector capability ref "${ref}" must use the "${exports.CONNECTOR_CAPABILITY_DOMAIN}" domain, got "${parsed.domain}".`,
+            raw: ref,
+        });
+    }
+    if (parsed.verbPath.length !== 2) {
+        throw new errors_1.CapabilityRefParseError({
+            message: `Connector capability ref "${ref}" must be exactly "<provider>.<verb>" after the domain (got ${parsed.verbPath.length} segment(s)).`,
+            raw: ref,
+        });
+    }
+    return {
+        provider: parsed.verbPath[0],
+        verb: parsed.verbPath[1],
+        major: parsed.major,
+        raw: parsed.raw,
+    };
+}
+//# sourceMappingURL=connector-capability-ref.js.map

package/dist/capability/lib/connector-capability-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-capability-ref.js","sourceRoot":"","sources":["../../../src/capability/lib/connector-capability-ref.ts"],"names":[],"mappings":";;;AAmDA,kEAiBC;AAeD,kEAsBC;AAzGD,qDAI0B;AAC1B,qCAAmD;AAiBtC,QAAA,2BAA2B,GAAG,WAAW,CAAC;AA6BvD,SAAgB,2BAA2B,CACzC,YAAoB,EACpB,IAAY,EACZ,KAAK,GAAG,CAAC;IAET,MAAM,GAAG,GAAG,IAAA,oCAAmB,EAAC;QAC9B,MAAM,EAAE,mCAA2B;QACnC,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,CAAC;QAC9B,KAAK;KACN,CAAC,CAAC;IAMH,2BAA2B,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,GAAG,CAAC;AACb,CAAC;AAeD,SAAgB,2BAA2B,CACzC,GAAW;IAEX,MAAM,MAAM,GAAG,IAAA,mCAAkB,EAAC,GAAG,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,mCAA2B,EAAE,CAAC;QAClD,MAAM,IAAI,gCAAuB,CAAC;YAChC,OAAO,EAAE,6BAA6B,GAAG,mBAAmB,mCAA2B,kBAAkB,MAAM,CAAC,MAAM,IAAI;YAC1H,GAAG,EAAE,GAAG;SACT,CAAC,CAAC;IACL,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,gCAAuB,CAAC;YAChC,OAAO,EAAE,6BAA6B,GAAG,+DAA+D,MAAM,CAAC,QAAQ,CAAC,MAAM,eAAe;YAC7I,GAAG,EAAE,GAAG;SACT,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAE;QAC7B,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAE;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;KAChB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/capability/index.ts

@@ -1,4 +1,5 @@
 export * from './lib/capability-ref';
+export * from './lib/connector-capability-ref';
 export * from './lib/capability-grant';
 export * from './lib/capability-policy';
 export * from './lib/permission-profile';

package/src/capability/lib/connector-capability-ref.ts

@@ -0,0 +1,106 @@
+import {
+  type CapabilityRef,
+  formatCapabilityRef,
+  parseCapabilityRef,
+} from './capability-ref';
+import { CapabilityRefParseError } from './errors';
+
+/**
+ * The single domain literal for every connector capability ref.
+ *
+ * Every connector operation — regardless of which backend fulfils it
+ * (`native-provider` / `external-mcp` / `openapi-bridge` / `email`, see
+ * `ConnectorAdapterKind` in the `connector` surface) — is projected into ONE
+ * canonical ref of the shape:
+ *
+ *   `connector:<provider>.<verb>@<major>`
+ *
+ * i.e. domain `connector`, resource = the provider slug, a single verb
+ * segment, and a major version. This is a stricter shape than the generic
+ * `CapabilityRef` grammar (which permits arbitrary `.`-joined verb paths); a
+ * connector ref is ALWAYS exactly `<provider>.<verb>` after the colon.
+ */
+export const CONNECTOR_CAPABILITY_DOMAIN = 'connector';
+
+/**
+ * Structured parts of a connector capability ref. `provider` is the resource
+ * segment, `verb` the single operation segment, `major` the ref's major
+ * version.
+ */
+export interface ParsedConnectorCapabilityRef {
+  readonly provider: string;
+  readonly verb: string;
+  readonly major: number;
+  readonly raw: CapabilityRef;
+}
+
+/**
+ * The single SSOT for constructing a connector capability ref. Delegates to
+ * `formatCapabilityRef` so the canonical grammar (lowercase kebab, positive
+ * integer major) is validated in exactly one place — never hand-write a
+ * `connector:...@N` literal.
+ *
+ * @param providerSlug lowercase-kebab provider slug (`github`, `smtp`, …).
+ * @param verb         single lowercase-kebab operation verb
+ *                     (`create-pull-request`, `send`, …).
+ * @param major        ref major version, default `1`. Connector refs version
+ *                     like syscalls.
+ *
+ * Throws `CapabilityRefParseError` if the inputs would produce a ref that does
+ * not match the canonical grammar (fail-fast — never returns an invalid ref).
+ */
+export function buildConnectorCapabilityRef(
+  providerSlug: string,
+  verb: string,
+  major = 1,
+): CapabilityRef {
+  const raw = formatCapabilityRef({
+    domain: CONNECTOR_CAPABILITY_DOMAIN,
+    verbPath: [providerSlug, verb],
+    major,
+  });
+  // Re-parse through the connector parser so the builder can ONLY ever emit a
+  // canonical exactly-`<provider>.<verb>` connector ref. This rejects a
+  // `providerSlug`/`verb` that smuggles in an extra `.` segment (which the
+  // generic grammar would otherwise accept), guaranteeing every value produced
+  // here round-trips through `parseConnectorCapabilityRef`.
+  parseConnectorCapabilityRef(raw);
+  return raw;
+}
+
+/**
+ * Parse a connector capability ref into its structured parts. Delegates to
+ * `parseCapabilityRef` for grammar validation, then enforces the connector
+ * shape:
+ *
+ * - domain MUST be `connector`;
+ * - the portion after `:` MUST be exactly two segments (`<provider>.<verb>`).
+ *
+ * Throws `CapabilityRefParseError` (code `CAPABILITY_REF_INVALID`) on any
+ * violation — never returns `null`, never silently coerces. This is the
+ * inverse of `buildConnectorCapabilityRef`: every value produced by the
+ * builder round-trips through this parser.
+ */
+export function parseConnectorCapabilityRef(
+  ref: string,
+): ParsedConnectorCapabilityRef {
+  const parsed = parseCapabilityRef(ref);
+  if (parsed.domain !== CONNECTOR_CAPABILITY_DOMAIN) {
+    throw new CapabilityRefParseError({
+      message: `Connector capability ref "${ref}" must use the "${CONNECTOR_CAPABILITY_DOMAIN}" domain, got "${parsed.domain}".`,
+      raw: ref,
+    });
+  }
+  if (parsed.verbPath.length !== 2) {
+    throw new CapabilityRefParseError({
+      message: `Connector capability ref "${ref}" must be exactly "<provider>.<verb>" after the domain (got ${parsed.verbPath.length} segment(s)).`,
+      raw: ref,
+    });
+  }
+  return {
+    provider: parsed.verbPath[0]!,
+    verb: parsed.verbPath[1]!,
+    major: parsed.major,
+    raw: parsed.raw,
+  };
+}