@xemahq/kernel-contracts 0.57.0 → 0.58.0

package/dist/capability/lib/capability-reach.d.ts

@@ -9,5 +9,8 @@ export declare const DEFAULT_CAPABILITY_REACH = CapabilityReach.Owner;
 export declare const REACH_RANK: Readonly<Record<CapabilityReach, number>>;
 export declare function reachWithin(candidate: CapabilityReach, ceiling: CapabilityReach): boolean;
 export declare function joinReach(derived: CapabilityReach, declared?: CapabilityReach | undefined): CapabilityReach;
-export declare function deriveReachFromInvocationKind(invocationKind: string): CapabilityReach;
+export declare function deriveCapabilityReach(input: {
+    readonly ref?: string;
+    readonly invocationKind?: string;
+}): CapabilityReach;
 //# sourceMappingURL=capability-reach.d.ts.map

package/dist/capability/lib/capability-reach.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-reach.d.ts","sourceRoot":"","sources":["../../../src/capability/lib/capability-reach.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmCxB,oBAAY,eAAe;IAKzB,KAAK,UAAU;IAMf,WAAW,gBAAgB;IAM3B,QAAQ,aAAa;CACtB;AAED,eAAO,MAAM,qBAAqB,mCAAgC,CAAC;AAQnE,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAQ9D,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAI/D,CAAC;AAGH,wBAAgB,WAAW,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAEzF;AAeD,wBAAgB,SAAS,CACvB,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,GACrC,eAAe,CAGjB;AAaD,wBAAgB,6BAA6B,CAAC,cAAc,EAAE,MAAM,GAAG,eAAe,CAIrF"}
+{"version":3,"file":"capability-reach.d.ts","sourceRoot":"","sources":["../../../src/capability/lib/capability-reach.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqCxB,oBAAY,eAAe;IAKzB,KAAK,UAAU;IAMf,WAAW,gBAAgB;IAM3B,QAAQ,aAAa;CACtB;AAED,eAAO,MAAM,qBAAqB,mCAAgC,CAAC;AAQnE,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAQ9D,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAI/D,CAAC;AAGH,wBAAgB,WAAW,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAEzF;AAeD,wBAAgB,SAAS,CACvB,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,GACrC,eAAe,CAGjB;AA6BD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAE3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,eAAe,CAWlB"}

package/dist/capability/lib/capability-reach.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.REACH_RANK = exports.DEFAULT_CAPABILITY_REACH = exports.CapabilityReachSchema = exports.CapabilityReach = void 0;
 exports.reachWithin = reachWithin;
 exports.joinReach = joinReach;
-exports.deriveReachFromInvocationKind = deriveReachFromInvocationKind;
+exports.deriveCapabilityReach = deriveCapabilityReach;
 const zod_1 = require("zod");
+const connector_capability_ref_1 = require("./connector-capability-ref");
 var CapabilityReach;
 (function (CapabilityReach) {
     CapabilityReach["Owner"] = "owner";
@@ -26,9 +27,21 @@ function joinReach(derived, declared) {
         return derived;
     return exports.REACH_RANK[declared] > exports.REACH_RANK[derived] ? declared : derived;
 }
-function deriveReachFromInvocationKind(invocationKind) {
-    return invocationKind === 'connector'
-        ? CapabilityReach.Integration
-        : exports.DEFAULT_CAPABILITY_REACH;
+function deriveCapabilityReach(input) {
+    if (input.invocationKind === 'connector') {
+        return CapabilityReach.Integration;
+    }
+    if (input.ref !== undefined &&
+        refDomain(input.ref) === connector_capability_ref_1.CONNECTOR_CAPABILITY_DOMAIN) {
+        return CapabilityReach.Integration;
+    }
+    return exports.DEFAULT_CAPABILITY_REACH;
+}
+function refDomain(ref) {
+    const separator = ref.indexOf(':');
+    if (separator <= 0) {
+        return undefined;
+    }
+    return ref.slice(0, separator);
 }
 //# sourceMappingURL=capability-reach.js.map

package/dist/capability/lib/capability-reach.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability-reach.js","sourceRoot":"","sources":["../../../src/capability/lib/capability-reach.ts"],"names":[],"mappings":";;;AA8EA,kCAEC;AAeD,8BAMC;AAaD,sEAIC;AAtHD,6BAAwB;AAmCxB,IAAY,eAkBX;AAlBD,WAAY,eAAe;IAKzB,kCAAe,CAAA;IAMf,8CAA2B,CAAA;IAM3B,wCAAqB,CAAA;AACvB,CAAC,EAlBW,eAAe,+BAAf,eAAe,QAkB1B;AAEY,QAAA,qBAAqB,GAAG,OAAC,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AAQtD,QAAA,wBAAwB,GAAG,eAAe,CAAC,KAAK,CAAC;AAQjD,QAAA,UAAU,GAA8C,MAAM,CAAC,MAAM,CAAC;IACjF,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1B,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,CAAC;IAChC,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;CAC9B,CAAC,CAAC;AAGH,SAAgB,WAAW,CAAC,SAA0B,EAAE,OAAwB;IAC9E,OAAO,kBAAU,CAAC,SAAS,CAAC,IAAI,kBAAU,CAAC,OAAO,CAAC,CAAC;AACtD,CAAC;AAeD,SAAgB,SAAS,CACvB,OAAwB,EACxB,QAAsC;IAEtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC3C,OAAO,kBAAU,CAAC,QAAQ,CAAC,GAAG,kBAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AACzE,CAAC;AAaD,SAAgB,6BAA6B,CAAC,cAAsB;IAClE,OAAO,cAAc,KAAK,WAAW;QACnC,CAAC,CAAC,eAAe,CAAC,WAAW;QAC7B,CAAC,CAAC,gCAAwB,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"capability-reach.js","sourceRoot":"","sources":["../../../src/capability/lib/capability-reach.ts"],"names":[],"mappings":";;;AAgFA,kCAEC;AAeD,8BAMC;AA6BD,sDAgBC;AApJD,6BAAwB;AAExB,yEAAyE;AAmCzE,IAAY,eAkBX;AAlBD,WAAY,eAAe;IAKzB,kCAAe,CAAA;IAMf,8CAA2B,CAAA;IAM3B,wCAAqB,CAAA;AACvB,CAAC,EAlBW,eAAe,+BAAf,eAAe,QAkB1B;AAEY,QAAA,qBAAqB,GAAG,OAAC,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AAQtD,QAAA,wBAAwB,GAAG,eAAe,CAAC,KAAK,CAAC;AAQjD,QAAA,UAAU,GAA8C,MAAM,CAAC,MAAM,CAAC;IACjF,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1B,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,CAAC;IAChC,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;CAC9B,CAAC,CAAC;AAGH,SAAgB,WAAW,CAAC,SAA0B,EAAE,OAAwB;IAC9E,OAAO,kBAAU,CAAC,SAAS,CAAC,IAAI,kBAAU,CAAC,OAAO,CAAC,CAAC;AACtD,CAAC;AAeD,SAAgB,SAAS,CACvB,OAAwB,EACxB,QAAsC;IAEtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC3C,OAAO,kBAAU,CAAC,QAAQ,CAAC,GAAG,kBAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AACzE,CAAC;AA6BD,SAAgB,qBAAqB,CAAC,KAKrC;IACC,IAAI,KAAK,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;QACzC,OAAO,eAAe,CAAC,WAAW,CAAC;IACrC,CAAC;IACD,IACE,KAAK,CAAC,GAAG,KAAK,SAAS;QACvB,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,sDAA2B,EACpD,CAAC;QACD,OAAO,eAAe,CAAC,WAAW,CAAC;IACrC,CAAC;IACD,OAAO,gCAAwB,CAAC;AAClC,CAAC;AAUD,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AACjC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.57.0",
+  "version": "0.58.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/lib/capability-reach.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+import { CONNECTOR_CAPABILITY_DOMAIN } from './connector-capability-ref';
+
 /**
  * `CapabilityReach` — DECLARED answer to "how far outside the owner does
  * invoking this capability reach?".
@@ -19,13 +21,13 @@ import { z } from 'zod';
  * declarations. Adding an integration capability is a one-line declaration at
  * the producer; no edit to `authorization-api`, and no way to forget one.
  *
- * PRECEDENCE — declared wins, derivation is the floor
- * ---------------------------------------------------
- * Absent ⇒ derived. A `connector`-kind invocation binding reaches an external
- * system by construction, so it derives {@link CapabilityReach.Integration}
- * with no declaration at all. Everything else derives
- * {@link CapabilityReach.Owner}, which is the SAFE default: it grants nothing
- * beyond what the owner already holds.
+ * PRECEDENCE — declared RAISES, derivation is the floor
+ * -----------------------------------------------------
+ * Absent ⇒ derived. A capability that is a connector — by its invocation
+ * binding OR by its ref domain, see {@link deriveCapabilityReach} — derives
+ * {@link CapabilityReach.Integration} with no declaration at all. Everything
+ * else derives {@link CapabilityReach.Owner}, which is the SAFE default: it
+ * grants nothing beyond what the owner already holds.
  *
  * A declaration may therefore only ever be needed to RAISE reach above the
  * derived floor (an http-bound capability that nonetheless touches org-wide
@@ -104,16 +106,60 @@ export function joinReach(
 /**
  * The reach a capability has by construction, before any declaration.
  *
- * A `connector`-kind invocation binding reaches a connected external system —
- * that is what a connector IS — so it derives {@link CapabilityReach.Integration}
- * with no author involvement. Every other binding kind derives the safe floor;
- * raising it is the author's explicit act.
+ * TWO independent structural signals, either of which is sufficient. Both are
+ * facts about the capability that the platform already holds — neither is a
+ * guess, and neither needs an author to remember anything:
+ *
+ *  1. **The invocation binding kind.** A `connector`-kind binding reaches a
+ *     connected external system — that is what a connector IS.
+ *  2. **The ref domain.** A ref in the `connector` domain
+ *     ({@link CONNECTOR_CAPABILITY_DOMAIN}) is a connector capability by the
+ *     ref grammar itself, which is a typed contract, not a naming convention.
+ *
+ * Signal 2 is not redundant, and leaving it out was a real bug: connector
+ * capabilities are today published with `http` invocation bindings (they are
+ * invoked through the connector gateway over HTTP), so binding-kind alone
+ * derives `owner` and every `connector:*` ref silently drops out of the
+ * `connected` reach tier. That is the exact failure mode — a capability quietly
+ * outside the tier that names it — this whole mechanism replaced a
+ * hand-maintained roster to prevent.
+ *
+ * Everything else derives the safe floor; raising it is the author's explicit
+ * act via a declared `reach`.
+ *
+ * Kept here, beside the enum, so the projector, the registry and the tier
+ * resolver cannot drift on what "derived" means.
+ */
+export function deriveCapabilityReach(input: {
+  /** Canonical capability ref. Unparseable refs contribute no signal. */
+  readonly ref?: string;
+  /** `CapabilityInvocationBinding.kind`, when the capability declares one. */
+  readonly invocationKind?: string;
+}): CapabilityReach {
+  if (input.invocationKind === 'connector') {
+    return CapabilityReach.Integration;
+  }
+  if (
+    input.ref !== undefined &&
+    refDomain(input.ref) === CONNECTOR_CAPABILITY_DOMAIN
+  ) {
+    return CapabilityReach.Integration;
+  }
+  return DEFAULT_CAPABILITY_REACH;
+}
+
+/**
+ * Domain segment of a capability ref, or `undefined` when the ref does not
+ * parse.
  *
- * Kept here, beside the enum, so the projector and the tier resolver cannot
- * drift on what "derived" means.
+ * Deliberately does NOT throw: this is a derivation input, and a malformed ref
+ * must contribute no reach signal rather than abort the read path that is
+ * validating it. The ref's own validation happens where it is written.
  */
-export function deriveReachFromInvocationKind(invocationKind: string): CapabilityReach {
-  return invocationKind === 'connector'
-    ? CapabilityReach.Integration
-    : DEFAULT_CAPABILITY_REACH;
+function refDomain(ref: string): string | undefined {
+  const separator = ref.indexOf(':');
+  if (separator <= 0) {
+    return undefined;
+  }
+  return ref.slice(0, separator);
 }