stigg-governance

Stigg ガバナンス — エンティティ単位の使用量制限

ガバナンスは、Stigg のクレジットと機能にエンティティ単位の制限適用を追加します。クレジットが「この顧客はどれだけ消費できるか？」に答えるのに対し、ガバナンスは「この顧客の独自の下位単位はどれだけ消費できるか？」に答えます。ベンダーが制限したい対象を、階層的な集計とハードリミットの適用によって制御できます。エンティティモデルは任意で、顧客が定義します。Stigg は固定の階層を設けていないため、決めつけないでください（ステップ 1 を参照）。

Stigg のガバナンスは、Stigg MCP を通じて操作します。execute ツールで SDK コードを実行し、search_docs で正確な形式を確認します。これにより、エージェントはエンティティタイプ、エンティティ、エンティティエンタイトルメント、ツリークエリ、単発のチェックを調査、設定、テスト確認できます。すべて SDK の v1 名前空間（client.v1.…）を使って execute 経由で実行します。本番環境でのランタイム適用は別の仕組みです。実際の顧客リクエストを制御するライブのエンタイトルメントチェックは、MCP 経由ではなく、ベンダーのホットパスで Stigg SDK／エッジを介して実行されます。MCP はエージェント側の設定と調査に使うもので、リクエスト時のゲートではありません。このスキルが扱うのはメンタルモデルです。接続、キー、セットアップは対象外で、それらは stigg-mcp スキルの担当です。

ガバナンスは v1 API で GA です。client.v1.* の呼び出しを使用してください。client.v1Beta.* のガバナンス呼び出しも引き続き動作しますが、非推奨です。ただし例外が 1 つあります。ガバナンスのツリークエリには v1 版がないため、引き続き client.v1Beta を使用します。既存の v1-beta コードについては、以下の v1-beta からの移行を参照してください。

ステップ 1 — モデルを聞き出す：決めつけずに尋ねる（エンティティタイプを定義する前に実行）

**ガバナンスのエンティティモデルは完全に任意で、顧客が定義します。**デフォルトの階層はありません。Stigg には何も組み込まれていません。部門／チーム／エージェントといった構造は、あくまで可能性の 1 つであり、テンプレートではありません。エンティティタイプを 1 つでも定義する前に、顧客が何を管理したいかを尋ね、回答に厳密に基づいて構築してください。階層を提案したり、決めつけたりしてはいけません。次の点を尋ねてください。

• どの単位を制限しますか？（顧客独自の用語。チーム、プロジェクト、地域、テナント、サブアカウント、コストセンター、エージェント、ワークスペースなど）
• どのように入れ子にし、集計しますか？（何が何を含むか、何階層までか。ツリーは最大 8 階層です）
• 実際に制限を設定するのはどの階層ですか？（制限を保持する階層、または集計が必要な階層だけをツリーに含め、残りは省略します）
• 使用量イベント上で単位を識別するものは何ですか？（イベントがすでに出力しているディメンションキー。これらが帰属キーになります）

回答に基づいてモデルを構築します。「プロジェクト単位で制限し、プロジェクトはクライアントに属します」なら、client → project を構築します。以下およびリファレンスにあるすべての実例は、可能なモデルの 1 つです。API の形式を示すものであり、採用すべきモデルを示すものではありません。

**手順：**モデルを聞き出す（このステップ）→ エンティティタイプ → エンティティ → エンティティエンタイトルメント → ランタイム。

前提条件 — 制限対象によって異なります

ガバナンスの制限は、既存の機能またはクレジット通貨に追加で適用されるものであり、それらに取って代わるものではありません。機能とクレジット通貨では必要なものが異なります — それぞれ異なる経路をたどるため、エンティティの権限（featureId または currencyId）に該当する行を確認してください。

• 機能（featureId）— 機能を利用できるアクティブなサブスクリプションが必要です。 ゲーティングチェックに合格できるのは、顧客がその機能を利用できる ACTIVE サブスクリプションを持っている場合に限られます — それ以外の場合は、標準的な理由（NoActiveSubscription、NoFeatureEntitlementInSubscription ＝ サブスクリプションに加入しているが、プランにその機能がない）で拒否されます。ガバナンスは引き続き実行され、chains が返される場合もありますが、チェックには合格できません。チェックに合格できるようにするには、事前にアクティブなサブスクリプションを通じて機能を利用可能にしてください。 エンティティの権限の upsert では権限の検証は行われません — 権限のない機能にも制限を設定できるため、問題は後のチェック時に初めて表面化します。カタログとサブスクリプションを先に設定し（stigg-pricing-modeling ／ stigg-subscriptions を参照）、その後に制限を設定してください。

• クレジット通貨（currencyId）— サブスクリプションは不要です。 クレジットは別の経路で処理されます。チェックでは顧客のクレジットプールを直接参照し、アクティブなサブスクリプションや割り当て済みのプランがなくてもクレジットを付与・消費できます。クレジット制限に必要なのは、存在するクレジット通貨と資金があるプール（付与分 — 定期、前払い、プロモーション、または手動）です。stigg-credits で通貨を設定してから、エンティティごとの制限を追加してください。

機能カタログ（プラン、機能、サブスクリプション — FREE プランでは公開前に charges.pricingType が必要です）の設定は、ガバナンスの役割ではありません。カタログは stigg-pricing-modeling、プロビジョニングは stigg-subscriptions を使って設定してください。クレジット通貨と付与分は stigg-credits で管理します。その後、エンティティごとの制限を追加してください。

始める前に

包括的な stigg スキルの指針に従い、まず検索してください。 作成前に search_docs（または Mintlify Stigg docs MCP）を使って、操作名、フィールド名、リクエストボディの形式を確認してください。このスキルがメンタルモデルを示し、実際のインターフェイスが形式を定めます。

4 つの要素

entity type → entity → entity entitlement → governance tree — タイプ（帰属キーを定義するもの）は環境ごとに一度だけ定義し、エンティティとして顧客ごとに作成します。エンティティの権限は、必要に応じてスコープを絞り込んだうえで、1 つの (entity, featureId|currencyId) の組み合わせを制限します。ツリーは使用量と制限の状況を報告しますが、ゲーティングは行いません。エンティティの権限は、v1-beta でassignment と呼ばれていたものです。各要素について、以下で詳しく説明します。

エンティティタイプ

エンティティタイプは、Step 1 で顧客が指定したもの（プロジェクト、リージョン、テナント、コストセンター、エージェントなど）にあたる、顧客配下の単位の種類を定義します。重要なのは、その帰属キーです。これは、使用量イベントがどのエンティティに属するかを識別する、イベントのディメンションキーのことです。エンティティタイプは環境ごとに一度だけ定義され、その環境内のすべての顧客で共有されます。操作は、list、upsert（一括 PUT、冪等）、archive、および checkActiveEntities です。エンティティタイプのエンティティが（いずれかの顧客で）1 つでもアクティブな場合、アーカイブは 400 で失敗します。まず checkActiveEntities(id) を呼び出し、エンティティをアーカイブしてからタイプをアーカイブしてください。アーカイブ済みのタイプを upsert すると復元されます。includeArchived: 'true' を渡さない限り、list ではアーカイブ済みのタイプは表示されません。使用量を報告する前に帰属キーを設計してください。過去のイベントにさかのぼって帰属情報を付与することはできません。

エンティティ

エンティティは、これらのタイプのインスタンスであり、顧客ごとに作成されます（顧客の配下に作成）。顧客ごとに複数作成でき、Step 1 で明らかになった任意の形（例：client → project、または region → tenant → workspace）で、深さは最大 8 レベルです。ツリー内のノードを配置または移動するには、エンティティ権限の upsert で parentId を設定します（client.v1.customers.entities.entitlements.upsert）。これは三状態で、省略＝親を変更しない、null＝ルートにする、エンティティ ID＝親を設定／変更する、です。parentId はエンティティの単一の親（エンティティごとに 1 つの位置）であり、機能や通貨ごとではなく、エンティティ権限に設定します。（実務上の注意：エンティティの upsert は parentId を受け付けず、metadata に構造上の役割はないため、親の設定はエンティティ権限の upsert で行います。）操作：一覧表示／取得／upsert（一括 PUT）／アーカイブ。アーカイブ解除はありません。アーカイブ済みエンティティを upsert すると復元されます。アーカイブ済みのエンティティタイプに属するエンティティは upsert できません（400）。親の再設定はリーフのみ可能です（リーフ以外の移動は拒否され、アーカイブ済みの子も子として数えられます）。アーカイブにはリーフの制限がありません。親をアーカイブすると、アクティブな子は孤児になるため、子孫は自分でボトムアップにアーカイブ／再配置してください。全ルールについては、references/entity-model.md を参照してください。

エンティティを同期する

エンティティは、ベンダーの信頼できる情報源を継続的に反映するものであり、一度だけインポートするものではありません。階層はまず自分のシステムに存在し、ツリーはその投影です。モデルを変更するコードパスにガバナンス操作を組み込みます。登録 → エンティティを upsert、名前変更／属性変更 → 冪等な再 upsert、プロビジョニング解除／削除 → アーカイブ（ボトムアップ）、再有効化 → アーカイブ済みエンティティを再 upsert、構造変更 → エンティティ権限の upsert で parentId を設定してノードを移動（リーフのみ）。upsert は冪等な一括 PUT なので、「各同期時に望ましいツリーをプッシュする」という宣言的なパターンが機能します。マッピングの全容と、未リリースの割り当て返却に関する注意点については、references/entity-lifecycle.md を参照してください。

エンティティ権限 — 制限

エンティティ権限は、1 つの (entity, featureId|currencyId) の組み合わせに使用制限を設定します。

• entityId — 制限対象のエンティティ（顧客のツリー内の任意のレベル）。
• featureId または currencyId — 制限対象。指定するのは必ずどちらか 1 つです。featureId（従量制機能）または currencyId（クレジット通貨）を指定します。両者は相互排他的です。
• usageLimit — ケイデンス期間の制限です。null = 無制限：上限はありませんが、使用量は引き続き追跡されます。
• cadence — リセット期間を表す、単一単位の ISO-8601 期間です。例：'P1M'（毎月）、'P10D'（10 日ごと）、'PT1H'（毎時）。単位は 1 つだけでなければならず、'P1M10D'（1 か月と10 日）のような複合形式は許可されません。
• scopeEntityIds — 任意。ディメンションスコープのサブリミットを定義し、制限が適用される条件を絞り込みます。[]（空）＝常に適用されるノード全体の制限です。空でない場合（例：['model-gpt4o']）、リスト内のすべてのエンティティがリクエストの解決済みセット（帰属情報から得られる祖先とディメンションの一致項目）に含まれる場合にのみ、制限が適用されます。ID は最大 5 個で、重複は許可されません。エンティティ配下のすべてに適用する代わりに、特定のエンティティ（通常はディメンションエンティティ）に使用します。

操作：一覧表示／upsert。upsert 1 回あたり最大 100 行です。upsert リクエスト本文のキーは entityEntitlements です（v1-beta では assignments が使用されていました）。行は (entityId, featureId|currencyId, scopeEntityIds) で照合されます。一致するものは更新され（省略された usageLimit／cadence は保持されます）、それ以外は新規作成されます（どちらの値も必須です）。したがって、異なるスコープに同じ機能を設定する場合、制限は別々になります。currencyId のエンティティ権限はクレジットの消費を制限するもので、請求通貨（USD/EUR）とは無関係です。具体例については、references/entity-entitlements.md を参照してください。

使用量の報告 — メータータイプによる使い分け

取り込みでアクセスを制限することはありません。消費量を記録し、ツリーを集計します。使用するエンドポイントは、対象機能のメータータイプによって異なります。

• 計算型／増分型メーター（アプリで数値を計算する場合）→ client.v2.usage.report：同期処理です。応答には各測定値の使用量と、data.entities に集計対象となった各エンティティのエンタイトルメントの使用量が含まれます。必須項目：customerId、featureId（機能 ID。クレジット通貨 ID を指定すると FeatureNotFound が発生します）、value。（client.v1.usage.report は非推奨です。）
• 未加工イベント型メーター（Stigg が未加工イベントを集計する場合 — 件数／合計／ユニーク数）→ client.v1.events.report（reportEvent）：現時点で必須の報告経路です（v2.usage.report では未加工イベント型メーターの機能を報告できません。代わりに events.report／reportEvent を使用してください）。大量処理に対応し、結果整合性を採用しています。reportEvent に featureId はありません。メーターは eventName（および idempotencyKey）で照合されます。

どちらも dimensions にアトリビューション情報を含めます（エンティティタイプの attributionKey の値。例：{ "projectId": "proj-atlas", "regionId": "eu-west" }）。これにより、一致するエンティティ とすべての祖先 に使用量が紐付けられます。

機能のメーターを確認して、使用する経路を選んでください。 Feature 型では hasMeter／meter／meterType が公開されています。meter 設定を確認し、未加工イベント型メーター（→ events.report）か、計算型／増分型メーター（→ v2.usage.report）かを判断してください。meterType だけでは「未加工イベント」を判別できないことに注意してください（未加工イベント型の機能であっても INCREMENTAL と表示される場合があります）。そのため、meter 設定を確認し、フィールドは search_docs で確かめてください。確実なフォールバックとして、v2.usage.report で CannotReportUsageForEntitlementWithMeterError が発生した場合は未加工イベント型メーターなので、events.report に切り替えてください。データ形式と例：references/enforcement-and-usage.md。

アクセス制御と使用量の読み取り

読み取り方法は 2 種類あり、混同しないでください。これは ホットパス（アクセス制御）とコールドパス（可観測性） の使い分けです。全体像は references/enforcement-vs-observability.md を参照してください。

1. アクセス（リクエストを制限）： 標準のエンタイトルメント チェック — client.v1.customers.checkEntitlement(customerId, { ... }) を使用し、featureId または currencyId、任意の requestedUsage（既定値は 1）、およびアトリビューション用の dimensions を渡します。dimensions を指定すると、ガバナンス上限もチェックされます。少なくとも 1 つのエンティティエンタイトルメントが適用される場合、応答の data.chains に経路上の各上限が列挙され、ガバナンスによる拒否は RequestedUsageExceedingLimit として返されます。いずれかの祖先がハードリミットに達すると、そのエンティティはブロックされます。子に上限の余裕があっても、親のいずれかが上限に達していればブロックされます。機能（featureId）のチェックには、有効なサブスクリプションによるエンタイトルメントも必要です。クレジット（currencyId）のチェックには必要ありません（「前提条件」を参照）。
2. 使用量と上限（可観測性）： ガバナンスツリーのクエリ — client.v1Beta.customers.governance.list(customerId, { ... }) は v1-beta のままでページネーションに対応し、エンティティノードを返します。残りの上限 ＝ usageLimit − currentUsage。既定ではツリーのみが返され、usageLimit／currentUsage／utilization／cadence は null になります。 対象の機能／クレジット通貨の設定と使用量を取得するには、featureIds および／または currencyIds（配列）を渡してください。使用量の数値は 数秒遅れる場合があります（未加工イベントではさらに遅れることがあります）。ダッシュボードやアラートに使用し、アクセス制御には 決して 使用しないでください。詳細な仕様：references/enforcement-and-usage.md。

サーフェスマップ

操作は、MCP の execute ツールを通じて @stigg/typescript SDK 呼び出しとして実行します（バルクアップサートは冪等です。バルクアップサートとアーカイブでは、1 回の呼び出しにつき最大 100 件を処理できます）。各操作 → 対応する SDK 呼び出し（MCP execute 経由）：

• エンティティタイプ — 一覧表示／アップサート（バルク）／アーカイブ／checkActiveEntities — client.v1.entityTypes.*
• エンティティ — 一覧表示／取得／アップサート（バルク、アーカイブ済みのエンティティも復元）／アーカイブ — client.v1.customers.entities.*（retrieve(entityId, { id: customerId })）
• エンティティのエンタイトルメント — 一覧表示／アップサート（本文のキーは entityEntitlements） — client.v1.customers.entities.entitlements.*
• エンタイトルメントの確認（ガバナンスの有効化状態にかかわらずアクセスを制御します） — client.v1.customers.checkEntitlement(customerId, { ... })
• ガバナンスツリーのクエリ（ハイドレーションには featureIds／currencyIds を渡します。ページネーション対応、v1-beta のみ） — client.v1Beta.customers.governance.list(customerId, { ... })
• 取り込み — 計算型／増分型メーター — client.v2.usage.report
• 取り込み — 生イベント型メーター（eventName による指定） — client.v1.events.report

操作名やデータ構造を推測せず、正確な操作を search_docs で確認してください。

API と UI — エンティティのエンタイトルメントモデルが異なるのは意図的な仕様です。 API では、エンティティごとに1 つの機能またはクレジット通貨を対象とするエンティティエンタイトルメントを扱います（(entity, featureId|currencyId)）。ダッシュボード UI で親の下にエンティティを作成すると、配置を保持するため、選択した機能またはクレジット通貨ごとに、無制限のエンティティエンタイトルメント（usageLimit: null）を 1 つ作成します（上限は行ごとに編集します）。最上位のエンティティには作成されません。そのため、UI と API で作成したエンティティの見た目は異なります。驚く必要はありません。一方に合わせてもう一方を「修正」しないでください。

Stigg MCP 経由の場合： MCP が公開するのは execute（SDK を使ったサンドボックス化された TypeScript）と search_docs のみで、エンドポイントごとに 1 つのツールが割り当てられているわけではありません。ガバナンス操作は、上記の SDK 名前空間を使って execute 経由で実行します。接続、キー、環境の設定は stigg-mcp スキルの役割です。execute または search_docs に接続できない場合のトラブルシューティングも、このスキルを参照してください。

v1-beta からの移行

client.v1Beta のガバナンス呼び出しは非推奨です。それぞれ v1 の呼び出しに対応しており、各行のフィールド名は変わりません。

• v1Beta.entityTypes.list / upsert → v1.entityTypes.list / upsert（v1 では archive と checkActiveEntities が追加されています）
• v1Beta.customers.entities.list / retrieve / upsert / archive → v1.customers.entities の同名操作
• v1Beta.customers.entities.unarchive → アーカイブ済みエンティティの ID を指定した v1.customers.entities.upsert
• v1Beta.customers.assignments.list / upsert → v1.customers.entities.entitlements.list / upsert。アップサート本文のキーは assignments から entityEntitlements に変わります
• v1Beta.customers.entitlements.check → v1.customers.checkEntitlement（featureId／currencyId／requestedUsage／dimensions パラメーターは同じです）
• v1Beta.customers.governance.list → 変更なし（v1 版はありません）
• 非推奨の v1.usage.report → v2.usage.report。応答には data.entities が追加されます

生の REST API も同様に /api/v1-beta/... → /api/v1/... と移行します。名称が変わるのは次の 1 件です：/api/v1-beta/customers/{id}/assignments → /api/v1/customers/{id}/entities/entitlements。

このスキルを使用しない場合

• アカウントレベルのクレジット通貨、付与、プール、台帳、自動チャージ → stigg-credits。
• エンティティごとの上限を設けずに機能のゲーティングや使用量のレポートを行う場合 → stigg-entitlements。
• カタログで機能／プラン／クレジット通貨をモデル化する場合 → stigg-pricing-modeling。
• サブスクリプションのプロビジョニング／キャンセル → stigg-subscriptions。

よくある間違い

それぞれの間違いと対処法：

• client.v1Beta で新しいコードを書く — これらのガバナンス呼び出しは非推奨です。v1 の呼び出しを使用してください（「v1-beta からの移行」を参照）。ツリークエリだけは client.v1Beta のままです。
• v1 のアップサートに assignments を送る — v1 の本文キーは entityEntitlements です。
• unarchive を呼び出す — v1 にはありません。アーカイブ済みのエンティティを同じ ID で再アップサートして復元します。
• アクティブなエンティティが残っているエンティティタイプをアーカイブする — リクエスト全体が 400 エラーで失敗します。checkActiveEntities(id) で確認し、まずタイプに属するエンティティをアーカイブしてから、タイプをアーカイブします。
• ツリークエリを基にアクセスを制御する — 使用量の数値には数秒の遅延が生じる場合があります。エンタイトルメントのチェックだけで制御してください。
• 「子には上限が残っているのにブロックされる」ことをバグとして調査する — これは祖先ノードの仕様です。祖先ノードのいずれかが上限に達すると、サブツリー全体がブロックされます。ツリーを上方向に確認してください。
• 階層を 8 レベルより深くする — 厳格な上限があり、それより深い配置は拒否されます。モデルを再設計してください（たとえば、1 レベルを scopeEntityIds にまとめます）。
• アトリビューションキーのディメンションを指定せずに使用量を報告する — 使用量はどのエンティティにも帰属せず、上限も累積されません。ディメンションはあらかじめ設計してください。
• 常に v2.usage.report、または常に events.report を呼び出す — どちらを使うかはメーターの種類によって異なります。計算値／増分値には v2.usage.report、生イベントには events.report（eventName を指定する reportEvent）を使います。v2.usage.report が CannotReportUsageForEntitlementWithMeterError を返した場合は、reportEvent に切り替えてください。
• クレジット通貨 ID を使用量レポートの featureId として渡す — featureId のみを受け付けるため、FeatureNotFound で失敗します。クレジット API（stigg-credits）から直接クレジットを引き出してください。
• reportEvent に featureId を渡す — reportEvent は featureId ではなく、eventName（および idempotencyKey）でメーターを指定します。アトリビューションは dimensions で指定します。
• feature（featureId）のエンティティエンタイトルメントを作成し、チェックが通ることを期待する — アップサートではエンタイトルメントの検証は行われません。まず有効なサブスクリプションを通じて feature にエンタイトルメントを付与する必要があります。そうでなければ、チェックは NoActiveSubscription／NoFeatureEntitlementInSubscription で拒否されます。
• credit（currencyId）の上限にも feature と同じようにサブスクリプションが必要だと思い込む — 必要ありません。クレジットは別の経路で処理されます。チェックはクレジットプールを直接読み取ります。サブスクリプションがなくても、クレジットを付与・消費できます。必要なのはサブスクリプションではなく、クレジット通貨と資金が投入されたプールです（stigg-credits）。
• usageLimit: null をゼロとして扱う — null は無制限を意味します。使用量は引き続き累積され、ロールアップされます。
• ツリーを読み取り、上限／使用量が null になる — ツリーのみのモードです。設定と使用量を反映するには、featureIds／currencyIds を渡してください。
• MCP の接続エラーをガバナンスの問題として扱う — 接続／セットアップの問題（無効なキー、誤った環境など）は stigg-mcp の担当範囲です。そこで修正してから、ガバナンス操作を再実行してください。
• 子が残っているノードの親を変更する — 親の変更はリーフノードに限られます。リーフ以外の移動は拒否されます。子を別の親に移すか、parentId: null を指定して下から順に親子関係を解除してから、元の親を移動してください。子をアーカイブしても解決しません。アーカイブ済みの子も対象に含まれます。この拒否は一時的なものではないため、再試行しないでください。
• アーカイブはリーフノードに限られると思い込む — そうではありません。親をアーカイブすると、アクティブな子は孤立します。子孫を自分で下から順にアーカイブまたは再配置してください。プラットフォームは処理を阻止しません。
• エンティティのアップサート（または metadata）に parentId を指定する — エンティティのアップサートでは parentId が拒否され、metadata に構造上の役割はありません。ノードを配置／移動するには、エンティティエンタイトルメントのアップサートに parentId を設定します。
• エンティティを一度きりのインポートとして扱う — エンティティは信頼できる情報源を継続的に反映するものです。作成／更新／削除／再構成の処理に、アップサート／アーカイブ／親の変更を組み込んでください（references/entity-lifecycle.md）。
• currencyId を請求通貨として解釈する — これはクレジット通貨（stigg-credits を参照）であり、USD／EUR ではありません。
• ガバナンス用にエンドポイントごとの MCP ツールがあると思い込む — MCP にあるのは execute と search_docs だけです。execute を通じて SDK を操作してください。