mcp-usage-control-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,135 @@
+# mcp-usage-control-mcp
+
+MCP TypeScript SDK v2 adapter for `mcp-usage-control`.
+
+> **Current distribution status:** this package is not published to npm yet. Use the repository checkout or locally packed `mcp-usage-control` + `mcp-usage-control-mcp` tarballs. See [Use from source / local tarballs](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/using-from-source.md) / [日本語](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/using-from-source.ja.md).
+
+## English
+
+`protectTool()` wraps **single-round** `@modelcontextprotocol/server` v2 tool handlers with admission, cost-liable activation, lease heartbeat, MCP-aware result classification, and explicit settlement.
+
+`protectMultiRoundTool()` is the opt-in wrapper for MCP v2 `input_required` flows. It keeps one logical usage reservation across fresh MCP retry requests instead of reserving again for every round.
+
+For a tool with no input schema, set `noInput: true`. For input-schema tools, omit it. The adapter normalizes the SDK no-input callback/runtime shape without guessing whether `{}` is real input.
+
+It distinguishes normal success, `{ isError: true }`, and thrown errors. Invalid/throwing cost classifiers cause the full reservation to be settled before `UsageClassificationError` is surfaced. Ambiguous settlement failures are surfaced as `UsageSettlementError` and are not blindly retried.
+
+### Returning a bounded remaining value
+
+Successful core admission exposes the authoritative store-produced `remainingByBudget`. The MCP wrappers intentionally do not inject balances into handler results. If a tool must return a bounded remaining value to its consumer, use the core lifecycle directly at that integration point and select only the application-approved budget value:
+
+```ts
+const admission = await control.reserve(request);
+if (!admission.allowed) throw new UsageDeniedError(admission.reason);
+
+const remaining = admission.remainingByBudget.find(
+  balance => balance.key === expectedBudgetKey,
+)?.remaining;
+
+const lease = admission.lease;
+await lease.markLiable();
+const value = await runTool();
+await lease.settle(1, 'success');
+
+return {
+  content: [
+    {
+      type: 'text',
+      text: JSON.stringify({ value, ...(remaining === undefined ? {} : { remaining }) }),
+    },
+  ],
+};
+```
+
+Do not recompute the balance from configured limits in the MCP layer; the usage store is authoritative. Budget keys can contain application-sensitive or high-cardinality identity, so do not expose the key itself to the model/client or promote it to metric labels by default. Prefer a single numeric value selected by application policy.
+
+### Multi-round trust boundary
+
+MCP `requestState` round-trips through the client and is untrusted. `protectMultiRoundTool()` therefore does **not** put the usage lease in client state and does not trust a client-supplied flow identifier by itself.
+
+- configure the MCP server's `requestState.verify` hook, for example with the official SDK `createRequestStateCodec()`;
+- pass the matching mint function through `requestState.mint`;
+- keep `McpUsageFlowRecord` server-side;
+- use a `McpUsageFlowStore` whose `consume()` atomically compares the principal/tool/args binding and consumes the flow exactly once;
+- use `MemoryMcpUsageFlowStore` only for tests or a single-process server, and instantiate it outside a per-request `createMcpHandler` factory;
+- distributed servers must provide a durable/shared implementation with the same atomic compare-and-consume contract.
+
+The wrapper owns the wire `requestState`. A handler-authored `requestState` is retained only in trusted server-side flow storage and is supplied on the next round as `flow.applicationRequestState`.
+
+`suspendTtlMs` is explicit. The lease is already cost-liable before the application handler runs; if a suspended/claimed flow is abandoned, expiry conservatively retains the full reservation rather than refunding a possibly executed operation.
+
+Resume tokens are one-time. A concurrent or repeated resume after one caller has claimed the token fails closed instead of re-running the handler. This prevents duplicate execution/reservation, but it is not a general exactly-once side-effect or response-replay mechanism; applications that require replay of a completed business result need their own business-idempotency/result store.
+
+- [Current source/tarball usage](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/using-from-source.md)
+- [MCP integration](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/mcp-integration.md)
+- [API reference](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/api-reference.md)
+- [Architecture](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/architecture.md)
+
+The application remains responsible for trusted principal/tenant derivation, authentication/authorization, retry-stable logical operation IDs, durable flow storage when horizontally scaled, and provider-specific fencing after lease loss.
+
+## 日本語
+
+`protectTool()` は `@modelcontextprotocol/server` v2の **single-round** tool handlerをusage admission、cost-liable activation、lease heartbeat、MCP-aware result classification、explicit settlementでwrapします。
+
+`protectMultiRoundTool()` はMCP v2 `input_required` 向けのopt-in wrapperです。fresh MCP retry requestごとに再reserveせず、1つのlogical usage reservationをround間で維持します。
+
+input schemaがないtoolでは `noInput: true` を指定し、input schemaありでは省略します。SDKのno-input callback / runtime shapeをnormalizeしますが、`{}` がreal inputかどうかを推測しません。
+
+normal success、`{ isError: true }`、thrown errorを区別します。classifierがthrow / invalid unitsを返した場合はfull reservationをsettleしてから `UsageClassificationError` を表面化します。ambiguous settlement failureは `UsageSettlementError` として表面化しblind retryしません。
+
+### boundedなremaining値を返す
+
+coreのadmission成功結果には、authoritative storeが算出した `remainingByBudget` が含まれます。MCP wrapperはbalanceをhandler resultへ自動注入しません。tool consumerへboundedなremaining値を返したい場合は、そのintegration pointだけcore lifecycleを直接使い、applicationが許可したbudgetの値だけを選択します。
+
+```ts
+const admission = await control.reserve(request);
+if (!admission.allowed) throw new UsageDeniedError(admission.reason);
+
+const remaining = admission.remainingByBudget.find(
+  balance => balance.key === expectedBudgetKey,
+)?.remaining;
+
+const lease = admission.lease;
+await lease.markLiable();
+const value = await runTool();
+await lease.settle(1, 'success');
+
+return {
+  content: [
+    {
+      type: 'text',
+      text: JSON.stringify({ value, ...(remaining === undefined ? {} : { remaining }) }),
+    },
+  ],
+};
+```
+
+MCP layerでconfigured limitからbalanceを再計算しないでください。usage storeがsource of truthです。budget keyにはapplication-sensitive / high-cardinalityなidentityが含まれ得るため、key自体をmodel/clientへ出したりmetric labelへ自動昇格したりしません。application policyで選択した単一のnumeric valueだけを返す形を推奨します。
+
+### Multi-roundのtrust boundary
+
+MCP `requestState` はclientを往復するためuntrustedです。`protectMultiRoundTool()` はusage leaseをclient stateへ入れず、client supplied flow IDだけをaccounting authorityとして信用しません。
+
+- MCP server側で `requestState.verify` を設定します。公式SDKの `createRequestStateCodec()` を利用できます。
+- 対応するmint関数を `requestState.mint` へ渡します。
+- `McpUsageFlowRecord` はserver-sideに保持します。
+- `McpUsageFlowStore.consume()` はprincipal / tool / args bindingを比較し、matchしたflowだけをatomicにone-time consumeする必要があります。
+- `MemoryMcpUsageFlowStore` はtestまたはsingle-process server専用です。per-request `createMcpHandler` factoryの外側で生成してください。
+- horizontal scaleするserverでは同じatomic compare-and-consume contractを満たすshared/durable storeを用意してください。
+
+wire上の `requestState` はwrapperが所有します。application handlerが返した `requestState` はtrusted server-side flow storageだけに保持し、次roundでは `flow.applicationRequestState` として渡します。
+
+`suspendTtlMs` は明示必須です。application handlerへ入る前にleaseはすでにcost-liableなので、suspend / claim後にflowがabandonされた場合はexpiryでfull reservationを保守的に維持し、実行済みかもしれない処理をrefundしません。
+
+resume tokenはone-timeです。同じtokenのconcurrent/repeated resumeは1 callerがclaimした後fail-closeし、handlerを再実行しません。これはduplicate execution / duplicate reservationを防ぎますが、汎用的なexactly-once side effectやcompleted response replayを保証するものではありません。business resultのreplayが必要なapplicationは既存のbusiness idempotency / result storeを併用してください。
+
+- [現在のsource / tarball利用手順](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/using-from-source.ja.md)
+- [MCP integration](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/mcp-integration.ja.md)
+- [API reference](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/api-reference.ja.md)
+- [Architecture](https://github.com/git-ksk/mcp-usage-control/blob/main/docs/architecture.ja.md)
+
+trustedなprincipal / tenant derivation、authentication / authorization、retry-stable logical operation ID、horizontal scale時のdurable flow storage、lease loss後のprovider-specific fencingはapplication側の責務です。
+
+## Vector workloads (v0.7)
+
+`protectTool()` remains the bounded scalar convenience wrapper. Heterogeneous request/token/compute workloads should use the explicit `VectorUsageControl` / `VectorUsageLease` lifecycle from `mcp-usage-control` so every required dimension is reserved, grown, and settled atomically before metered work proceeds.

package/dist/flow-store-conformance.d.ts

@@ -0,0 +1,42 @@
+import type { McpUsageFlowStore } from './index.js';
+type MaybePromise<T> = T | Promise<T>;
+export interface McpUsageFlowStoreConformanceHarness {
+    /** Return an isolated flow-store domain for one scenario. */
+    createStore(scenario: string): MaybePromise<McpUsageFlowStore>;
+    /** Wait until a flow with the supplied TTL is authoritatively expired. */
+    waitForFlowExpiry(ttlMs: number, scenario: string): MaybePromise<void>;
+    /** Optional cleanup for the isolated scenario domain. */
+    cleanup?(scenario: string): MaybePromise<void>;
+    /** Flow lifetime used by the expiry case. Defaults to 40 ms. */
+    flowTtlMs?: number;
+    /** Parallel consumers used by the one-time claim race. Defaults to 16. */
+    concurrency?: number;
+}
+export interface McpUsageFlowStoreConformanceCaseResult {
+    name: string;
+    passed: boolean;
+    error?: string;
+}
+export interface McpUsageFlowStoreConformanceReport {
+    passed: boolean;
+    cases: McpUsageFlowStoreConformanceCaseResult[];
+}
+export declare class McpUsageFlowStoreConformanceError extends Error {
+    readonly report: McpUsageFlowStoreConformanceReport;
+    constructor(report: McpUsageFlowStoreConformanceReport);
+}
+/**
+ * Verify the portable compare-and-consume contract required by
+ * protectMultiRoundTool().
+ *
+ * Passing proves behavioral one-time claim semantics, including the requirement
+ * that `consume()` reject expiry before returning a record using the store's own
+ * authoritative time domain. Callers treat a returned record as expiry-valid and
+ * do not re-check it against an unrelated host clock. Production-safe flow stores
+ * must additionally document durability/HA and prove that a lost consume ACK does
+ * not trigger caller-side blind retry/re-entry.
+ */
+export declare function runMcpUsageFlowStoreConformance(harness: McpUsageFlowStoreConformanceHarness): Promise<McpUsageFlowStoreConformanceReport>;
+export declare function assertMcpUsageFlowStoreConformance(harness: McpUsageFlowStoreConformanceHarness): Promise<McpUsageFlowStoreConformanceReport>;
+export {};
+//# sourceMappingURL=flow-store-conformance.d.ts.map

package/dist/flow-store-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-store-conformance.d.ts","sourceRoot":"","sources":["../src/flow-store-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,mCAAmC;IAClD,6DAA6D;IAC7D,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAE/D,0EAA0E;IAC1E,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEvE,yDAAyD;IACzD,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE/C,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sCAAsC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kCAAkC;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,sCAAsC,EAAE,CAAC;CACjD;AAED,qBAAa,iCAAkC,SAAQ,KAAK;aAC9B,MAAM,EAAE,kCAAkC;gBAA1C,MAAM,EAAE,kCAAkC;CASvE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,kCAAkC,CAAC,CAkE7C;AAED,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,kCAAkC,CAAC,CAI7C"}

package/dist/flow-store-conformance.js

@@ -0,0 +1,178 @@
+export class McpUsageFlowStoreConformanceError extends Error {
+    report;
+    constructor(report) {
+        const failed = report.cases.filter(result => !result.passed);
+        super(`McpUsageFlowStore conformance failed: ${failed
+            .map(result => `${result.name}: ${result.error ?? 'unknown failure'}`)
+            .join('; ')}`);
+        this.report = report;
+        this.name = 'McpUsageFlowStoreConformanceError';
+    }
+}
+/**
+ * Verify the portable compare-and-consume contract required by
+ * protectMultiRoundTool().
+ *
+ * Passing proves behavioral one-time claim semantics, including the requirement
+ * that `consume()` reject expiry before returning a record using the store's own
+ * authoritative time domain. Callers treat a returned record as expiry-valid and
+ * do not re-check it against an unrelated host clock. Production-safe flow stores
+ * must additionally document durability/HA and prove that a lost consume ACK does
+ * not trigger caller-side blind retry/re-entry.
+ */
+export async function runMcpUsageFlowStoreConformance(harness) {
+    const flowTtlMs = harness.flowTtlMs ?? 40;
+    const concurrency = harness.concurrency ?? 16;
+    assertPositiveInteger(flowTtlMs, 'flowTtlMs');
+    assertPositiveInteger(concurrency, 'concurrency');
+    const cases = [];
+    await runCase(harness, cases, 'one-time-consume', async (store) => {
+        const record = flowRecord('flow-contract-one-time-0001', 5_000);
+        await store.suspend(record);
+        const first = await store.consume(record.flowId, record.binding);
+        assert(first !== undefined, 'first matching consume must return the flow');
+        assertRecordMatches(first, record);
+        const replay = await store.consume(record.flowId, record.binding);
+        assert(replay === undefined, 'matching flow must be consumed at most once');
+    });
+    await runCase(harness, cases, 'binding-mismatch-preserves-legitimate-flow', async (store) => {
+        const record = flowRecord('flow-contract-binding-0001', 5_000);
+        await store.suspend(record);
+        const mismatches = [
+            { ...record.binding, principalId: 'other-principal' },
+            { ...record.binding, tenantId: 'other-tenant' },
+            { ...record.binding, tool: 'other-tool' },
+            { ...record.binding, argsHash: 'b'.repeat(64) },
+        ];
+        for (const mismatch of mismatches) {
+            const result = await store.consume(record.flowId, mismatch);
+            assert(result === undefined, 'binding mismatch must not return trusted flow state');
+        }
+        const legitimate = await store.consume(record.flowId, record.binding);
+        assert(legitimate !== undefined, 'binding mismatch must not consume legitimate flow state');
+        assertRecordMatches(legitimate, record);
+    });
+    await runCase(harness, cases, 'concurrent-one-time-consume', async (store) => {
+        const record = flowRecord('flow-contract-concurrent-0001', 5_000);
+        await store.suspend(record);
+        const results = await Promise.all(Array.from({ length: concurrency }, () => store.consume(record.flowId, record.binding)));
+        const winners = results.filter((result) => result !== undefined);
+        assert(winners.length === 1, `expected exactly one consume winner, got ${winners.length}`);
+        assertRecordMatches(winners[0], record);
+    });
+    await runCase(harness, cases, 'duplicate-suspend-fails', async (store) => {
+        const record = flowRecord('flow-contract-duplicate-0001', 5_000);
+        await store.suspend(record);
+        await assertRejects(() => Promise.resolve(store.suspend(record)), 'duplicate flow ID must fail');
+        const legitimate = await store.consume(record.flowId, record.binding);
+        assert(legitimate !== undefined, 'duplicate suspend failure must preserve original flow');
+    });
+    await runCase(harness, cases, 'expired-flow-cannot-resume', async (store) => {
+        const record = flowRecord('flow-contract-expiry-0001', flowTtlMs);
+        await store.suspend(record);
+        await harness.waitForFlowExpiry(flowTtlMs, 'expired-flow-cannot-resume');
+        const expired = await store.consume(record.flowId, record.binding);
+        assert(expired === undefined, 'expired flow must not resume');
+    });
+    return { passed: cases.every(result => result.passed), cases };
+}
+export async function assertMcpUsageFlowStoreConformance(harness) {
+    const report = await runMcpUsageFlowStoreConformance(harness);
+    if (!report.passed)
+        throw new McpUsageFlowStoreConformanceError(report);
+    return report;
+}
+async function runCase(harness, results, name, body) {
+    try {
+        const store = await harness.createStore(name);
+        await body(store);
+        results.push({ name, passed: true });
+    }
+    catch (error) {
+        results.push({ name, passed: false, error: errorMessage(error) });
+    }
+    finally {
+        try {
+            await harness.cleanup?.(name);
+        }
+        catch (error) {
+            results.push({ name: `${name}:cleanup`, passed: false, error: errorMessage(error) });
+        }
+    }
+}
+function flowRecord(flowId, ttlMs) {
+    const now = Date.now();
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > Number.MAX_SAFE_INTEGER - now) {
+        throw new RangeError('flow-store conformance ttlMs exceeds safe timestamp range');
+    }
+    const expiresAt = now + ttlMs;
+    return {
+        flowId,
+        binding: {
+            principalId: 'principal-1',
+            tenantId: 'tenant-1',
+            tool: 'contract-tool',
+            argsHash: 'a'.repeat(64),
+        },
+        lease: {
+            reservation: {
+                id: 'contract-reservation',
+                operationId: 'contract-operation',
+                principalId: 'principal-1',
+                tenantId: 'tenant-1',
+                tool: 'contract-tool',
+                budgetKeys: ['contract:budget'],
+                reservedUnits: 1,
+                expiresAt,
+            },
+            ttlMs,
+            unresolvedGrowth: {
+                incrementId: 'contract-growth-increment',
+                additionalUnits: 2,
+                budgets: [{ key: 'contract:budget', limit: 10 }],
+            },
+        },
+        round: 1,
+        expiresAt,
+    };
+}
+function assertRecordMatches(actual, expected) {
+    assert(actual.flowId === expected.flowId, 'flowId changed across storage');
+    assert(actual.round === expected.round, 'round changed across storage');
+    assert(actual.expiresAt === expected.expiresAt, 'expiresAt changed across storage');
+    assert(actual.binding.principalId === expected.binding.principalId, 'principal binding changed');
+    assert(actual.binding.tenantId === expected.binding.tenantId, 'tenant binding changed');
+    assert(actual.binding.tool === expected.binding.tool, 'tool binding changed');
+    assert(actual.binding.argsHash === expected.binding.argsHash, 'args binding changed');
+    assert(actual.lease.reservation.id === expected.lease.reservation.id, 'reservation identity changed across storage');
+    assert(JSON.stringify(actual.lease.unresolvedGrowth) === JSON.stringify(expected.lease.unresolvedGrowth), 'unresolved growth changed across storage');
+    if (expected.lease.unresolvedGrowth !== undefined) {
+        assert(actual.lease.unresolvedGrowth !== expected.lease.unresolvedGrowth, 'unresolved growth must be detached from caller state');
+        assert(actual.lease.unresolvedGrowth?.budgets !== expected.lease.unresolvedGrowth.budgets, 'unresolved growth budgets must be detached from caller state');
+    }
+}
+async function assertRejects(action, message) {
+    let rejected = false;
+    try {
+        await action();
+    }
+    catch {
+        rejected = true;
+    }
+    assert(rejected, message);
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function assertPositiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return `${error.name}: ${error.message}`;
+    return String(error);
+}
+//# sourceMappingURL=flow-store-conformance.js.map

package/dist/flow-store-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-store-conformance.js","sourceRoot":"","sources":["../src/flow-store-conformance.ts"],"names":[],"mappings":"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"}