@stigmer/sdk 3.14.0 → 3.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/sdk",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Stigmer TypeScript SDK — typed API client for all Stigmer platform resources",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,6 +45,6 @@
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@stigmer/protos": "3.14.0"
+    "@stigmer/protos": "3.15.0"
   }
 }

package/platform.d.ts

@@ -1,6 +1,6 @@
 import { type Transport } from "@connectrpc/connect";
-import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
-import type { DeploymentMode } from "./resource-availability.js";
+import type { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { type DeploymentMode } from "./resource-availability.js";
 /** Server identity information returned by {@link PlatformClient.getServerInfo}. */
 export interface ServerInfo {
     /** Server edition mapped to a {@link DeploymentMode}. */
@@ -23,8 +23,10 @@ export declare class PlatformClient {
     /**
      * Retrieve the connected server's edition and version.
      *
-     * Maps the proto {@link ServerEdition} to a {@link DeploymentMode}:
+     * Maps the proto {@link ServerEdition} to a {@link DeploymentMode}
+     * through {@link deploymentModeOf}:
      * - `oss` -> `"local"`
+     * - `enterprise` -> `"enterprise"`
      * - `cloud` -> `"cloud"`
      * - unspecified/unknown -> `"cloud"` (safe default)
      */

package/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAGL,aAAa,EACd,MAAM,uDAAuD,CAAC;AAG/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;gBAEtD,SAAS,EAAE,SAAS;IAIhC;;;;;;;OAOG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;CAc3C"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAMhF,OAAO,KAAK,EAEV,aAAa,EACd,MAAM,uDAAuD,CAAC;AAE/D,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAEpC,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;gBAEtD,SAAS,EAAE,SAAS;IAIhC;;;;;;;;;OASG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;CAc3C"}

package/platform.js

@@ -1,7 +1,8 @@
 import { createClient } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
-import { GetServerInfoInputSchema, PlatformQueryController, ServerEdition, } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { GetServerInfoInputSchema, PlatformQueryController, } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { wrapError } from "./gen/errors.js";
+import { deploymentModeOf, } from "./resource-availability.js";
 /**
  * Client for platform-level queries (server info, capabilities).
  *
@@ -17,8 +18,10 @@ export class PlatformClient {
     /**
      * Retrieve the connected server's edition and version.
      *
-     * Maps the proto {@link ServerEdition} to a {@link DeploymentMode}:
+     * Maps the proto {@link ServerEdition} to a {@link DeploymentMode}
+     * through {@link deploymentModeOf}:
      * - `oss` -> `"local"`
+     * - `enterprise` -> `"enterprise"`
      * - `cloud` -> `"cloud"`
      * - unspecified/unknown -> `"cloud"` (safe default)
      */
@@ -26,7 +29,7 @@ export class PlatformClient {
         try {
             const resp = await this.platform.getServerInfo(create(GetServerInfoInputSchema, {}));
             return {
-                deploymentMode: resp.edition === ServerEdition.oss ? "local" : "cloud",
+                deploymentMode: deploymentModeOf(resp.edition),
                 edition: resp.edition,
                 version: resp.version,
             };

package/platform.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA+B,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,aAAa,GACd,MAAM,uDAAuD,CAAC;AAE/D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAa5C;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAyC;IAElE,YAAY,SAAoB;QAC9B,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,aAAa;QACjB,IAAI,CAAC;YACH,MAAM,IAAI,GAAwB,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CACjE,MAAM,CAAC,wBAAwB,EAAE,EAAE,CAAC,CACrC,CAAC;YACF,OAAO;gBACL,cAAc,EAAE,IAAI,CAAC,OAAO,KAAK,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;gBACtE,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA+B,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,uDAAuD,CAAC;AAK/D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EACL,gBAAgB,GAEjB,MAAM,4BAA4B,CAAC;AAYpC;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAyC;IAElE,YAAY,SAAoB;QAC9B,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa;QACjB,IAAI,CAAC;YACH,MAAM,IAAI,GAAwB,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CACjE,MAAM,CAAC,wBAAwB,EAAE,EAAE,CAAC,CACrC,CAAC;YACF,OAAO;gBACL,cAAc,EAAE,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;gBAC9C,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}

package/resource-availability.d.ts

@@ -1,19 +1,60 @@
-import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 /**
- * Deployment mode of the Stigmer backend the client is connected to.
+ * The edition vocabulary of the SDK: which edition a server is, in the
+ * SDK's own words, and whether a resource kind is served there.
  *
- * - `"local"` — Running against the local Go CLI server (OSS).
- *   Only `open_source`-tier resources are available.
- * - `"cloud"` — Running against Stigmer Cloud.
- *   All resources (including `cloud_only`) are available.
+ * Four facts this module is built on (editions program, DD-001):
+ *
+ * - A kind's `ResourceTier` names the MINIMUM edition that serves it. The
+ *   editions are ordered oss < enterprise < cloud because each composes the
+ *   previous one's extension units, so a tier admits its own edition and
+ *   every edition above it.
+ * - The proto enums' numbers are wire identifiers, not ranks: `enterprise`
+ *   was added after `cloud` / `cloud_only` and sits at 3 in both. The two
+ *   rank functions below are the ONLY place a tier meets an edition; nothing
+ *   compares enum numbers.
+ * - `DeploymentMode` is `ServerEdition` in string-literal form, the shape
+ *   React consumers expect (`colorMode: "light" | "dark"` is the sibling),
+ *   with `oss` spelled `"local"` for history's sake. `deploymentModeOf` is
+ *   the ONE converter; it must never grow a second implementation.
+ * - An older client must not break against a newer server: an edition value
+ *   this SDK does not know maps to `"cloud"` (nothing hidden) instead of
+ *   throwing. The switch is exhaustive at compile time so a new edition is
+ *   still a compile error here; the runtime fallback is for the wire.
+ *
+ * `DeploymentMode` answers a TIER question ("is this kind served here?").
+ * Sites that use it to ask a FACILITY question ("does this server have a
+ * wallet?") compare `=== "cloud"` deliberately and say which facility they
+ * mean; see the React SDK's deployment-mode consumers.
+ */
+import { type ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+/**
+ * Edition of the Stigmer backend the client is connected to, as reported
+ * by {@link PlatformClient.getServerInfo}.
+ *
+ * - `"local"` — Stigmer, the open-source edition. `open_source`-tier
+ *   resources are served.
+ * - `"enterprise"` — Stigmer Enterprise, self-hosted. `open_source`- and
+ *   `enterprise`-tier resources are served.
+ * - `"cloud"` — Stigmer Cloud. Every resource is served.
+ */
+export type DeploymentMode = "local" | "enterprise" | "cloud";
+/**
+ * The one edition-to-mode converter.
+ *
+ * `server_edition_unspecified` and any value this SDK does not know map to
+ * `"cloud"`: a broken or newer server hides nothing, which is the failure a
+ * client can live with. The `never` default keeps the switch exhaustive for
+ * the editions this SDK knows.
  */
-export type DeploymentMode = "local" | "cloud";
+export declare function deploymentModeOf(edition: ServerEdition): DeploymentMode;
 /**
- * Check whether a resource kind is available in the given deployment mode.
+ * Check whether a resource kind is served in the given deployment mode.
  *
- * In cloud mode every resource is available. In local mode only
- * `open_source`-tier resources (those NOT in {@link CLOUD_ONLY_KINDS})
- * are available.
+ * A kind is served when the mode's edition ranks at or above the kind's
+ * minimum edition. Throws for a kind with no tier (only
+ * `api_resource_kind_unknown`): that is a programming error, and answering
+ * "available" for it would hide the bug.
  */
 export declare function isResourceAvailable(kind: ApiResourceKind, mode: DeploymentMode): boolean;
 //# sourceMappingURL=resource-availability.d.ts.map

package/resource-availability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-availability.d.ts","sourceRoot":"","sources":["../src/resource-availability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qFAAqF,CAAC;AAG3H;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,cAAc,GACnB,OAAO,CAGT"}
+{"version":3,"file":"resource-availability.d.ts","sourceRoot":"","sources":["../src/resource-availability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,qFAAqF,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,uDAAuD,CAAC;AAGtF;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CAevE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,cAAc,GACnB,OAAO,CAQT"}

package/resource-availability.js

@@ -1,14 +1,107 @@
-import { CLOUD_ONLY_KINDS } from "./gen/resource-availability.js";
 /**
- * Check whether a resource kind is available in the given deployment mode.
+ * The edition vocabulary of the SDK: which edition a server is, in the
+ * SDK's own words, and whether a resource kind is served there.
  *
- * In cloud mode every resource is available. In local mode only
- * `open_source`-tier resources (those NOT in {@link CLOUD_ONLY_KINDS})
- * are available.
+ * Four facts this module is built on (editions program, DD-001):
+ *
+ * - A kind's `ResourceTier` names the MINIMUM edition that serves it. The
+ *   editions are ordered oss < enterprise < cloud because each composes the
+ *   previous one's extension units, so a tier admits its own edition and
+ *   every edition above it.
+ * - The proto enums' numbers are wire identifiers, not ranks: `enterprise`
+ *   was added after `cloud` / `cloud_only` and sits at 3 in both. The two
+ *   rank functions below are the ONLY place a tier meets an edition; nothing
+ *   compares enum numbers.
+ * - `DeploymentMode` is `ServerEdition` in string-literal form, the shape
+ *   React consumers expect (`colorMode: "light" | "dark"` is the sibling),
+ *   with `oss` spelled `"local"` for history's sake. `deploymentModeOf` is
+ *   the ONE converter; it must never grow a second implementation.
+ * - An older client must not break against a newer server: an edition value
+ *   this SDK does not know maps to `"cloud"` (nothing hidden) instead of
+ *   throwing. The switch is exhaustive at compile time so a new edition is
+ *   still a compile error here; the runtime fallback is for the wire.
+ *
+ * `DeploymentMode` answers a TIER question ("is this kind served here?").
+ * Sites that use it to ask a FACILITY question ("does this server have a
+ * wallet?") compare `=== "cloud"` deliberately and say which facility they
+ * mean; see the React SDK's deployment-mode consumers.
+ */
+import { ResourceTier, } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { KIND_TIERS } from "./gen/resource-availability.js";
+/**
+ * The one edition-to-mode converter.
+ *
+ * `server_edition_unspecified` and any value this SDK does not know map to
+ * `"cloud"`: a broken or newer server hides nothing, which is the failure a
+ * client can live with. The `never` default keeps the switch exhaustive for
+ * the editions this SDK knows.
+ */
+export function deploymentModeOf(edition) {
+    switch (edition) {
+        case ServerEdition.oss:
+            return "local";
+        case ServerEdition.enterprise:
+            return "enterprise";
+        case ServerEdition.cloud:
+        case ServerEdition.server_edition_unspecified:
+            return "cloud";
+        default: {
+            const _exhaustive = edition;
+            void _exhaustive;
+            return "cloud";
+        }
+    }
+}
+/**
+ * Check whether a resource kind is served in the given deployment mode.
+ *
+ * A kind is served when the mode's edition ranks at or above the kind's
+ * minimum edition. Throws for a kind with no tier (only
+ * `api_resource_kind_unknown`): that is a programming error, and answering
+ * "available" for it would hide the bug.
  */
 export function isResourceAvailable(kind, mode) {
-    if (mode === "cloud")
-        return true;
-    return !CLOUD_ONLY_KINDS.has(kind);
+    const tier = KIND_TIERS.get(kind);
+    if (tier === undefined) {
+        throw new Error(`isResourceAvailable: kind ${kind} has no tier — only kinds with kind_meta can be asked about`);
+    }
+    return editionRank(mode) >= tierRank(tier);
+}
+/** Position of an edition in the oss < enterprise < cloud order. */
+function editionRank(mode) {
+    switch (mode) {
+        case "local":
+            return 1;
+        case "enterprise":
+            return 2;
+        case "cloud":
+            return 3;
+        default: {
+            const _exhaustive = mode;
+            throw new Error(`unknown deployment mode: ${String(_exhaustive)}`);
+        }
+    }
+}
+/** Position of a tier's minimum edition in the same order. */
+function tierRank(tier) {
+    switch (tier) {
+        case ResourceTier.open_source:
+            return 1;
+        case ResourceTier.enterprise:
+            return 2;
+        case ResourceTier.cloud_only:
+            return 3;
+        case ResourceTier.resource_tier_unspecified:
+            // A kind without a declared tier is treated as core: the generator
+            // emits every kind_meta tier verbatim, so this arm is reachable only
+            // by a proto that forgot the field, and hiding a kind is the worse
+            // failure for a client.
+            return 1;
+        default: {
+            const _exhaustive = tier;
+            throw new Error(`unknown resource tier: ${String(_exhaustive)}`);
+        }
+    }
 }
 //# sourceMappingURL=resource-availability.js.map

package/resource-availability.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-availability.js","sourceRoot":"","sources":["../src/resource-availability.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAYlE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAqB,EACrB,IAAoB;IAEpB,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"resource-availability.js","sourceRoot":"","sources":["../src/resource-availability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,YAAY,GAEb,MAAM,qFAAqF,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,uDAAuD,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAc5D;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,aAAa,CAAC,GAAG;YACpB,OAAO,OAAO,CAAC;QACjB,KAAK,aAAa,CAAC,UAAU;YAC3B,OAAO,YAAY,CAAC;QACtB,KAAK,aAAa,CAAC,KAAK,CAAC;QACzB,KAAK,aAAa,CAAC,0BAA0B;YAC3C,OAAO,OAAO,CAAC;QACjB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,KAAK,WAAW,CAAC;YACjB,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAqB,EACrB,IAAoB;IAEpB,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,6DAA6D,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,oEAAoE;AACpE,SAAS,WAAW,CAAC,IAAoB;IACvC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,OAAO,CAAC,CAAC;QACX,KAAK,OAAO;YACV,OAAO,CAAC,CAAC;QACX,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,IAAI,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,SAAS,QAAQ,CAAC,IAAkB;IAClC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,YAAY,CAAC,WAAW;YAC3B,OAAO,CAAC,CAAC;QACX,KAAK,YAAY,CAAC,UAAU;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,YAAY,CAAC,UAAU;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,YAAY,CAAC,yBAAyB;YACzC,mEAAmE;YACnE,qEAAqE;YACrE,mEAAmE;YACnE,wBAAwB;YACxB,OAAO,CAAC,CAAC;QACX,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,IAAI,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;AACH,CAAC"}

package/src/__tests__/ensure-identity-account.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Pins `ensureMyIdentityAccount` (`ensure-identity-account.ts`; 20260911.11
+ * A3): the ONE first-sign-in flow every surface runs — the console's
+ * `useIdentityAccountGate` delegates to it, the CLI's `auth whoami` and
+ * `auth login` call it — so a platform builder embedding Stigmer gets the
+ * same flow as a first-class import.
+ *
+ *   1. whoAmI answers → the account, `created: false`; nothing else is
+ *      called;
+ *   2. whoAmI is NOT_FOUND → `onProvisioning` fires once (the hook's
+ *      "provisioning" state), provisionMyAccount runs, the created account
+ *      comes back with `created: true`;
+ *   3. any other whoAmI error propagates untouched (UNAUTHENTICATED,
+ *      UNAVAILABLE, a network fault) — the caller's error UX owns it;
+ *   4. a provisionMyAccount failure propagates untouched (UNAVAILABLE when
+ *      the issuer's userinfo is down is the documented arm).
+ *
+ * The doubles reject with `StigmerError`, the vocabulary the real
+ * `IdentityAccountClient` speaks (every RPC failure passes through
+ * `wrapError`), so `isNotFound` — the SDK's one classifier — is what the
+ * helper is proven against (refinement 11, slice 4).
+ */
+import { Code } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import {
+  IdentityAccountSchema,
+  type IdentityAccount,
+} from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { describe, expect, it } from "vitest";
+
+import {
+  ensureMyIdentityAccount,
+  type IdentityAccountLane,
+} from "../ensure-identity-account";
+import { StigmerError } from "../gen/errors";
+
+interface Calls {
+  whoAmI: number;
+  provisionMyAccount: number;
+}
+
+function clientWith(behaviour: {
+  whoAmI: () => Promise<IdentityAccount>;
+  provisionMyAccount?: () => Promise<IdentityAccount>;
+}): { client: { identityAccount: IdentityAccountLane }; calls: Calls } {
+  const calls: Calls = { whoAmI: 0, provisionMyAccount: 0 };
+  const client = {
+    identityAccount: {
+      whoAmI: () => {
+        calls.whoAmI += 1;
+        return behaviour.whoAmI();
+      },
+      provisionMyAccount: () => {
+        calls.provisionMyAccount += 1;
+        return (
+          behaviour.provisionMyAccount ??
+          (() => Promise.reject(new Error("must not be called")))
+        )();
+      },
+    },
+  };
+  return { client, calls };
+}
+
+const EXISTING = create(IdentityAccountSchema, {
+  metadata: { id: "ida_existing" },
+  spec: { idpId: "auth0|existing" },
+});
+const CREATED = create(IdentityAccountSchema, {
+  metadata: { id: "ida_created" },
+  spec: { idpId: "auth0|created" },
+});
+
+const NOT_FOUND = () =>
+  new StigmerError(
+    "not-found",
+    "Identity account not found for the authenticated user",
+    Code.NotFound,
+  );
+
+describe("ensureMyIdentityAccount", () => {
+  it("answers the existing account without provisioning", async () => {
+    const { client, calls } = clientWith({
+      whoAmI: () => Promise.resolve(EXISTING),
+    });
+    const result = await ensureMyIdentityAccount(client);
+    expect(result).toEqual({ account: EXISTING, created: false });
+    expect(calls).toEqual({ whoAmI: 1, provisionMyAccount: 0 });
+  });
+
+  it("provisions on NOT_FOUND, telling the caller once that it is provisioning", async () => {
+    const { client, calls } = clientWith({
+      whoAmI: () => Promise.reject(NOT_FOUND()),
+      provisionMyAccount: () => Promise.resolve(CREATED),
+    });
+    let provisioning = 0;
+    const result = await ensureMyIdentityAccount(client, {
+      onProvisioning: () => (provisioning += 1),
+    });
+    expect(result).toEqual({ account: CREATED, created: true });
+    expect(provisioning).toBe(1);
+    expect(calls).toEqual({ whoAmI: 1, provisionMyAccount: 1 });
+  });
+
+  it("does not fire onProvisioning when the account already exists", async () => {
+    const { client } = clientWith({ whoAmI: () => Promise.resolve(EXISTING) });
+    let provisioning = 0;
+    await ensureMyIdentityAccount(client, {
+      onProvisioning: () => (provisioning += 1),
+    });
+    expect(provisioning).toBe(0);
+  });
+
+  it("propagates any other whoAmI error untouched — only NOT_FOUND means 'provision me'", async () => {
+    const unauthenticated = new StigmerError(
+      "unauthenticated",
+      "authentication token missing",
+      Code.Unauthenticated,
+    );
+    const { client, calls } = clientWith({
+      whoAmI: () => Promise.reject(unauthenticated),
+    });
+    await expect(ensureMyIdentityAccount(client)).rejects.toBe(unauthenticated);
+    expect(calls.provisionMyAccount).toBe(0);
+
+    // A value that is not a StigmerError at all (a lane double that does
+    // not wrap, a transport fault) is also "any other error": propagated
+    // as the same object, never classified as "provision me".
+    const network = new TypeError("Load failed");
+    const offline = clientWith({ whoAmI: () => Promise.reject(network) });
+    await expect(ensureMyIdentityAccount(offline.client)).rejects.toBe(network);
+  });
+
+  it("propagates a provisioning failure untouched (the issuer's userinfo down is UNAVAILABLE)", async () => {
+    const unavailable = new StigmerError(
+      "unavailable",
+      "Failed to fetch user profile from identity provider: userinfo answered 503",
+      Code.Unavailable,
+    );
+    const { client } = clientWith({
+      whoAmI: () => Promise.reject(NOT_FOUND()),
+      provisionMyAccount: () => Promise.reject(unavailable),
+    });
+    await expect(ensureMyIdentityAccount(client)).rejects.toBe(unavailable);
+  });
+});

package/src/__tests__/platform.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Pins PlatformClient.getServerInfo's edition-to-mode mapping: the client
+ * reports the server's edition through the one converter
+ * (`deploymentModeOf`), so a third edition on the wire reaches consumers
+ * as its own mode and never collapses into "cloud" by accident. The raw
+ * edition rides beside it for callers that want the wire value.
+ */
+import { describe, expect, it } from "vitest";
+import { createRouterTransport } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import {
+  GetServerInfoOutputSchema,
+  PlatformQueryController,
+  ServerEdition,
+} from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import { PlatformClient } from "../platform";
+
+function clientAnswering(edition: ServerEdition): PlatformClient {
+  return new PlatformClient(
+    createRouterTransport(({ service }) => {
+      service(PlatformQueryController, {
+        getServerInfo: () =>
+          create(GetServerInfoOutputSchema, { edition, version: "1.2.3" }),
+      });
+    }),
+  );
+}
+
+describe("PlatformClient.getServerInfo", () => {
+  it.each([
+    [ServerEdition.oss, "local"],
+    [ServerEdition.enterprise, "enterprise"],
+    [ServerEdition.cloud, "cloud"],
+  ] as const)(
+    "maps edition %d to deploymentMode %s and keeps the raw edition",
+    async (edition, mode) => {
+      const info = await clientAnswering(edition).getServerInfo();
+      expect(info.deploymentMode).toBe(mode);
+      expect(info.edition).toBe(edition);
+      expect(info.version).toBe("1.2.3");
+    },
+  );
+});

package/src/__tests__/resource-availability.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Pins the edition vocabulary (`resource-availability.ts`): the one
+ * edition-to-mode converter, the rank comparison behind
+ * `isResourceAvailable`, and the two properties the DDs assumed and this
+ * module has to make true —
+ *
+ *   - ranks, never wire numbers: `enterprise = 3` sits ABOVE `cloud = 2`
+ *     and `cloud_only = 2` on the wire, so a comparison on enum values
+ *     would say an Enterprise-tier kind is not served by a Cloud server;
+ *   - forward compatibility: an edition value this SDK does not know
+ *     (a newer server) maps to `"cloud"` instead of throwing, so an older
+ *     console never breaks against a newer server.
+ *
+ * The kinds named here are chosen one per tier; re-tiering any of them is
+ * a contract change and must touch this file (editions program, DD-001).
+ */
+import { describe, expect, it } from "vitest";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import {
+  deploymentModeOf,
+  isResourceAvailable,
+  type DeploymentMode,
+} from "../resource-availability";
+
+const MODES: readonly DeploymentMode[] = ["local", "enterprise", "cloud"];
+
+describe("deploymentModeOf — the one edition-to-mode converter", () => {
+  it("maps each known edition to its mode", () => {
+    expect(deploymentModeOf(ServerEdition.oss)).toBe("local");
+    expect(deploymentModeOf(ServerEdition.enterprise)).toBe("enterprise");
+    expect(deploymentModeOf(ServerEdition.cloud)).toBe("cloud");
+  });
+
+  it("maps unspecified to cloud — the documented safe default (nothing hidden on a broken server)", () => {
+    expect(deploymentModeOf(ServerEdition.server_edition_unspecified)).toBe(
+      "cloud",
+    );
+  });
+
+  it("maps an edition this SDK does not know to cloud instead of throwing — older client, newer server", () => {
+    // A future fourth edition arrives off the wire as a number the enum
+    // type does not name. The cast is the test's point.
+    expect(deploymentModeOf(99 as ServerEdition)).toBe("cloud");
+  });
+});
+
+describe("isResourceAvailable — a tier is a minimum edition", () => {
+  it("open_source-tier kinds are available in every mode", () => {
+    for (const mode of MODES) {
+      expect(isResourceAvailable(ApiResourceKind.agent, mode), mode).toBe(true);
+    }
+  });
+
+  it("enterprise-tier kinds are available in enterprise and cloud, not local", () => {
+    expect(isResourceAvailable(ApiResourceKind.iam_policy, "local")).toBe(
+      false,
+    );
+    expect(isResourceAvailable(ApiResourceKind.iam_policy, "enterprise")).toBe(
+      true,
+    );
+    // The inversion case: enterprise = 3 > cloud = 2 on the wire. A
+    // wire-number comparison fails exactly here.
+    expect(isResourceAvailable(ApiResourceKind.iam_policy, "cloud")).toBe(true);
+  });
+
+  it("cloud_only-tier kinds are available in cloud only", () => {
+    expect(
+      isResourceAvailable(ApiResourceKind.api_resource_version, "local"),
+    ).toBe(false);
+    expect(
+      isResourceAvailable(ApiResourceKind.api_resource_version, "enterprise"),
+    ).toBe(false);
+    expect(
+      isResourceAvailable(ApiResourceKind.api_resource_version, "cloud"),
+    ).toBe(true);
+  });
+
+  it("the kinds this entry re-tiers read as their new tier", () => {
+    // oauth_app: served by the OSS server; the cloud_only tier was drift.
+    expect(isResourceAvailable(ApiResourceKind.oauth_app, "local")).toBe(true);
+    // platform: the operator seat a self-hosting Enterprise company owns.
+    expect(isResourceAvailable(ApiResourceKind.platform, "local")).toBe(false);
+    expect(isResourceAvailable(ApiResourceKind.platform, "enterprise")).toBe(
+      true,
+    );
+    // identity_account: open_source since the open-source server serves the
+    // domain (20260911.11 slice 5); the tier moved in the same change as
+    // the serving code, never ahead of it.
+    expect(isResourceAvailable(ApiResourceKind.identity_account, "local")).toBe(
+      true,
+    );
+    // agent_share and channel_app: served by OSS; they never moved.
+    expect(isResourceAvailable(ApiResourceKind.agent_share, "local")).toBe(
+      true,
+    );
+    expect(isResourceAvailable(ApiResourceKind.channel_app, "local")).toBe(
+      true,
+    );
+  });
+
+  it("refuses a kind with no tier — a programming error, never silently available", () => {
+    expect(() =>
+      isResourceAvailable(ApiResourceKind.api_resource_kind_unknown, "cloud"),
+    ).toThrow(/no tier/);
+  });
+});