@methodts/runtime 0.1.0

package/dist/cost-governor/observations-store.test.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { ObservationsStore } from './observations-store.js';
+import { createAppendToken } from '../ports/historical-observations.js';
+// In-memory FileSystemProvider mock
+class MemFs {
+    files = new Map();
+    dirs = new Set();
+    readFileSync(path) {
+        const content = this.files.get(path);
+        if (content === undefined)
+            throw new Error(`ENOENT: ${path}`);
+        return content;
+    }
+    writeFileSync(path, content) {
+        this.files.set(path, content);
+    }
+    existsSync(path) {
+        return this.files.has(path) || this.dirs.has(path);
+    }
+    readdirSync(_path, options) {
+        return options?.withFileTypes ? [] : [];
+    }
+    statSync(_path) {
+        throw new Error('not implemented');
+    }
+    unlinkSync(path) {
+        this.files.delete(path);
+    }
+    mkdirSync(path) {
+        this.dirs.add(path);
+    }
+    renameSync(oldPath, newPath) {
+        const content = this.files.get(oldPath);
+        if (content !== undefined) {
+            this.files.set(newPath, content);
+            this.files.delete(oldPath);
+        }
+    }
+    realpathSync(path) { return path; }
+    async readFile(path) { return this.readFileSync(path); }
+    async writeFile(path, content) { this.writeFileSync(path, content); }
+    async appendFile(path, content) {
+        const existing = this.files.get(path) ?? '';
+        this.files.set(path, existing + content);
+    }
+    async readdir(_path) { return []; }
+    async stat(_path) { throw new Error('not implemented'); }
+    async access(_path) { }
+    async mkdir(path) { this.dirs.add(path); }
+}
+const sig = {
+    methodologyId: 'P2-SD',
+    capabilities: ['write'],
+    model: 'opus',
+    inputSizeBucket: 's',
+};
+const makeObs = (costUsd) => ({
+    signature: sig,
+    costUsd,
+    durationMs: 10_000,
+    tokensIn: 100,
+    tokensOut: 200,
+    tokensCacheRead: 0,
+    tokensCacheWrite: 0,
+    recordedAt: Date.now(),
+    accountId: 'default',
+    providerClass: 'claude-cli',
+});
+describe('ObservationsStore — basic', () => {
+    it('append then query round-trip', () => {
+        const fs = new MemFs();
+        const store = new ObservationsStore({ dataDir: '/data', hmacSecret: 'test-secret' }, fs);
+        store.recover();
+        const token = createAppendToken();
+        store.append(makeObs(0.10), token);
+        store.append(makeObs(0.20), token);
+        const results = store.query(sig);
+        assert.equal(results.length, 2);
+        // Newest first
+        assert.equal(results[0].costUsd, 0.20);
+        assert.equal(results[1].costUsd, 0.10);
+    });
+    it('query with limit', () => {
+        const fs = new MemFs();
+        const store = new ObservationsStore({ dataDir: '/data', hmacSecret: 'test' }, fs);
+        store.recover();
+        const token = createAppendToken();
+        for (let i = 0; i < 10; i++)
+            store.append(makeObs(i * 0.01), token);
+        const limited = store.query(sig, 3);
+        assert.equal(limited.length, 3);
+    });
+    it('persists to file with HMAC', () => {
+        const fs = new MemFs();
+        const store = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs);
+        store.recover();
+        store.append(makeObs(0.15), createAppendToken());
+        // Find the observations file
+        const filePaths = [...fs.files.keys()];
+        const jsonlPath = filePaths.find(p => p.includes('observations-'));
+        assert.ok(jsonlPath);
+        const content = fs.files.get(jsonlPath);
+        const line = content.trim();
+        const parsed = JSON.parse(line);
+        assert.ok(parsed.hmac);
+        assert.equal(typeof parsed.hmac, 'string');
+        assert.equal(parsed.hmac.length, 64); // sha256 hex
+    });
+    it('per-signature cap enforced', () => {
+        const fs = new MemFs();
+        const store = new ObservationsStore({ dataDir: '/data', hmacSecret: 'test', maxPerSignature: 3 }, fs);
+        store.recover();
+        const token = createAppendToken();
+        for (let i = 0; i < 5; i++)
+            store.append(makeObs(i * 0.1), token);
+        const all = store.query(sig);
+        assert.equal(all.length, 3); // capped
+    });
+});
+describe('ObservationsStore — integrity & recovery', () => {
+    it('loads valid observations on restart', () => {
+        const fs = new MemFs();
+        // Write some observations
+        const store1 = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs);
+        store1.recover();
+        const token = createAppendToken();
+        store1.append(makeObs(0.1), token);
+        store1.append(makeObs(0.2), token);
+        // New instance reads the same file
+        const store2 = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs);
+        const result = store2.recover();
+        assert.equal(result.validLines, 2);
+        assert.equal(result.skippedLines, 0);
+        assert.equal(store2.count(), 2);
+    });
+    it('skips lines with invalid HMAC', () => {
+        const fs = new MemFs();
+        const events = [];
+        const store1 = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs);
+        store1.recover();
+        store1.append(makeObs(0.1), createAppendToken());
+        // Corrupt by appending a line with bad HMAC
+        const filePath = [...fs.files.keys()].find(p => p.includes('observations-'));
+        const existing = fs.files.get(filePath);
+        const badLine = JSON.stringify({ ...makeObs(9.99), hmac: 'DEADBEEF' }) + '\n';
+        fs.files.set(filePath, existing + badLine);
+        const store2 = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs, (e) => events.push(e));
+        const result = store2.recover();
+        assert.equal(result.validLines, 1);
+        assert.equal(result.skippedLines, 1);
+        assert.ok(events.some(e => e.type === 'cost.integrity_violation'));
+    });
+    it('skips malformed JSON lines', () => {
+        const fs = new MemFs();
+        const events = [];
+        fs.writeFileSync(join('/data', `observations-${currentMonth()}.jsonl`), 'not json\n');
+        const store = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs, (e) => events.push(e));
+        const result = store.recover();
+        // Single bad line → total corruption path (no valid lines)
+        assert.equal(result.corruptedFile, true);
+        assert.ok(events.some(e => e.type === 'cost.observations_corrupted'));
+    });
+    it('wrong HMAC secret means nothing loads (renamed as corrupt)', () => {
+        const fs = new MemFs();
+        const events = [];
+        // Write with one secret
+        const writer = new ObservationsStore({ dataDir: '/data', hmacSecret: 'SECRET_A' }, fs);
+        writer.recover();
+        writer.append(makeObs(0.1), createAppendToken());
+        // Read with a different secret → should rename as corrupted
+        const reader = new ObservationsStore({ dataDir: '/data', hmacSecret: 'WRONG_SECRET' }, fs, (e) => events.push(e));
+        const result = reader.recover();
+        assert.equal(result.corruptedFile, true);
+        assert.ok(events.some(e => e.type === 'cost.observations_corrupted'));
+    });
+    it('handles empty file gracefully', () => {
+        const fs = new MemFs();
+        const store = new ObservationsStore({ dataDir: '/data', hmacSecret: 'secret' }, fs);
+        const result = store.recover();
+        assert.equal(result.validLines, 0);
+        assert.equal(result.corruptedFile, false);
+    });
+});
+function currentMonth() {
+    const now = new Date();
+    return `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+//# sourceMappingURL=observations-store.test.js.map

package/dist/cost-governor/observations-store.test.js.map

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

package/dist/cost-governor/percentile.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Percentile computation utilities for cost/duration estimation.
+ */
+/**
+ * Compute the p-th percentile from a sorted array of numbers.
+ * Uses linear interpolation between adjacent values.
+ *
+ * @param sorted - Pre-sorted array (ascending). Must not be empty.
+ * @param p - Percentile in [0, 100].
+ */
+export declare function percentile(sorted: readonly number[], p: number): number;
+/** Compute p50 and p90 from an unsorted array. */
+export declare function computeBands(values: readonly number[]): {
+    p50: number;
+    p90: number;
+};
+//# sourceMappingURL=percentile.d.ts.map

package/dist/cost-governor/percentile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"percentile.d.ts","sourceRoot":"","sources":["../../src/cost-governor/percentile.ts"],"names":[],"mappings":"AACA;;GAEG;AAEH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAMpF"}

package/dist/cost-governor/percentile.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Percentile computation utilities for cost/duration estimation.
+ */
+/**
+ * Compute the p-th percentile from a sorted array of numbers.
+ * Uses linear interpolation between adjacent values.
+ *
+ * @param sorted - Pre-sorted array (ascending). Must not be empty.
+ * @param p - Percentile in [0, 100].
+ */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        throw new Error('percentile: empty array');
+    if (sorted.length === 1)
+        return sorted[0];
+    const idx = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(idx);
+    const upper = Math.ceil(idx);
+    if (lower === upper)
+        return sorted[lower];
+    const frac = idx - lower;
+    return sorted[lower] * (1 - frac) + sorted[upper] * frac;
+}
+/** Compute p50 and p90 from an unsorted array. */
+export function computeBands(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        p50: percentile(sorted, 50),
+        p90: percentile(sorted, 90),
+    };
+}
+//# sourceMappingURL=percentile.js.map

package/dist/cost-governor/percentile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"percentile.js","sourceRoot":"","sources":["../../src/cost-governor/percentile.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;GAEG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,EAAE,CAAS;IAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACpE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAE1C,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE7B,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAE1C,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,CAAC;IACzB,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;AAC3D,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,YAAY,CAAC,MAAyB;IACpD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,OAAO;QACL,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;KAC5B,CAAC;AACJ,CAAC"}

package/dist/cost-governor/percentile.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=percentile.test.d.ts.map

package/dist/cost-governor/percentile.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"percentile.test.d.ts","sourceRoot":"","sources":["../../src/cost-governor/percentile.test.ts"],"names":[],"mappings":""}

package/dist/cost-governor/percentile.test.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { percentile, computeBands } from './percentile.js';
+describe('percentile', () => {
+    it('returns sole element for single-element array', () => {
+        assert.equal(percentile([42], 50), 42);
+        assert.equal(percentile([42], 90), 42);
+    });
+    it('computes p50 of even distribution', () => {
+        const sorted = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        const p50 = percentile(sorted, 50);
+        assert.ok(p50 >= 5 && p50 <= 6);
+    });
+    it('computes p90 of even distribution', () => {
+        const sorted = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        const p90 = percentile(sorted, 90);
+        assert.ok(p90 >= 9 && p90 <= 10);
+    });
+    it('p0 returns first element', () => {
+        assert.equal(percentile([10, 20, 30], 0), 10);
+    });
+    it('p100 returns last element', () => {
+        assert.equal(percentile([10, 20, 30], 100), 30);
+    });
+    it('interpolates between adjacent values', () => {
+        // [10, 20] p50 should be 15
+        assert.equal(percentile([10, 20], 50), 15);
+    });
+    it('throws on empty array', () => {
+        assert.throws(() => percentile([], 50));
+    });
+    it('handles identical values', () => {
+        assert.equal(percentile([5, 5, 5, 5], 50), 5);
+        assert.equal(percentile([5, 5, 5, 5], 90), 5);
+    });
+});
+describe('computeBands', () => {
+    it('computes p50 and p90 from unsorted array', () => {
+        const values = [10, 1, 5, 3, 8, 2, 7, 4, 9, 6];
+        const bands = computeBands(values);
+        assert.ok(bands.p50 >= 5 && bands.p50 <= 6);
+        assert.ok(bands.p90 >= 9 && bands.p90 <= 10);
+    });
+});
+//# sourceMappingURL=percentile.test.js.map

package/dist/cost-governor/percentile.test.js.map

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

package/dist/cost-governor/rate-governor-impl.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SingleAccountRateGovernor — implements RuntimeRateGovernor for a single
+ * account (no routing, no policies). Multi-account deferred to a future PRD.
+ *
+ * Uses TokenBucket for rate limiting and BackpressureQueue for callers
+ * waiting for capacity. On releaseSlot, optionally persists an observation
+ * via the injected onObservation callback.
+ *
+ * PRD-057 / S2 §8: Optional per-`appId` scoping. When `appId` is supplied
+ * to the constructor, slots track both `accountId` and `appId`, and
+ * `utilization()` accepts an optional `appId` filter. Absent = today's
+ * bridge behavior (bit-identical).
+ */
+import type { ProviderClass, SlotId, AccountUtilization, InvocationSignature } from '@methodts/types';
+import type { RuntimeRateGovernor, DispatchSlot, AcquireOptions, ObserveOutcome } from '../ports/rate-governor.js';
+/**
+ * Per-PRD-057 / S2 §8: Optional application identifier for per-tenant
+ * (Cortex AppId) scoping. Branded string to avoid collision with other
+ * string types. Declared locally in runtime until `@methodts/types` defines
+ * a canonical `AppId`; the downstream `@methodts/agent-runtime` (PRD-058)
+ * will likely re-brand.
+ */
+export type AppId = string & {
+    readonly __brand: 'AppId';
+};
+export interface RateGovernorImplConfig {
+    burstCapacity: number;
+    weeklyCap: number;
+    concurrentCap: number;
+    /** Max time to wait in queue before throwing SaturationError. */
+    queueWaitTimeoutMs?: number;
+}
+export interface SlotRecord {
+    slot: DispatchSlot;
+    /** Captured signature for observation recording (if known). */
+    signature?: InvocationSignature;
+}
+export type OnObservation = (outcome: ObserveOutcome, record: SlotRecord) => void;
+export declare class SingleAccountRateGovernor implements RuntimeRateGovernor {
+    private readonly config;
+    private readonly onObservation?;
+    private readonly bucket;
+    private readonly queue;
+    private readonly active;
+    private slotCounter;
+    private readonly accountId;
+    private readonly defaultTimeoutMs;
+    /**
+     * Optional per-tenant scope (PRD-057 / S2 §8). When undefined, the
+     * governor behaves bit-identically to bridge's today. When set, the
+     * slot-key becomes `${accountId}:${appId}` and emitted observations
+     * carry the `appId` via the optional slot field.
+     */
+    private readonly appId;
+    constructor(config: RateGovernorImplConfig, onObservation?: OnObservation | undefined, options?: {
+        appId?: AppId;
+    });
+    acquireSlot(opts: AcquireOptions): Promise<DispatchSlot>;
+    releaseSlot(outcome: ObserveOutcome): Promise<void>;
+    utilization(_providerClass: ProviderClass, appIdFilter?: AppId): readonly AccountUtilization[];
+    /** Expose the scoped `appId` (undefined = no scoping). */
+    getAppId(): AppId | undefined;
+    activeSlots(): readonly DispatchSlot[];
+    /**
+     * Track the signature for a slot so releaseSlot can emit an observation.
+     * Called by the throttler/strategy layer after acquireSlot.
+     */
+    attachSignature(slotId: SlotId, signature: InvocationSignature): void;
+    /** Sweep leaked slots whose maxLifetimeMs has elapsed. */
+    sweep(onLeak?: (slot: DispatchSlot) => void): number;
+    private makeSlot;
+}
+//# sourceMappingURL=rate-governor-impl.d.ts.map

package/dist/cost-governor/rate-governor-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-governor-impl.d.ts","sourceRoot":"","sources":["../../src/cost-governor/rate-governor-impl.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EAEN,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,cAAc,EACf,MAAM,2BAA2B,CAAC;AAKnC;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;AAElF,qBAAa,yBAA0B,YAAW,mBAAmB;IAgBjE,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAhBjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAGvB,MAAM,EAAE,sBAAsB,EAC9B,aAAa,CAAC,EAAE,aAAa,YAAA,EAC9C,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;IAYvB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IA4BxD,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAczD,WAAW,CACT,cAAc,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,KAAK,GAClB,SAAS,kBAAkB,EAAE;IAuBhC,0DAA0D;IAC1D,QAAQ,IAAI,KAAK,GAAG,SAAS;IAI7B,WAAW,IAAI,SAAS,YAAY,EAAE;IAItC;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB,GAAG,IAAI;IAKrE,0DAA0D;IAC1D,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM;IAiBpD,OAAO,CAAC,QAAQ;CAajB"}

package/dist/cost-governor/rate-governor-impl.js

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * SingleAccountRateGovernor — implements RuntimeRateGovernor for a single
+ * account (no routing, no policies). Multi-account deferred to a future PRD.
+ *
+ * Uses TokenBucket for rate limiting and BackpressureQueue for callers
+ * waiting for capacity. On releaseSlot, optionally persists an observation
+ * via the injected onObservation callback.
+ *
+ * PRD-057 / S2 §8: Optional per-`appId` scoping. When `appId` is supplied
+ * to the constructor, slots track both `accountId` and `appId`, and
+ * `utilization()` accepts an optional `appId` filter. Absent = today's
+ * bridge behavior (bit-identical).
+ */
+import { SaturationError } from '@methodts/pacta';
+import { TokenBucket } from './token-bucket.js';
+import { BackpressureQueue } from './backpressure-queue.js';
+export class SingleAccountRateGovernor {
+    config;
+    onObservation;
+    bucket;
+    queue = new BackpressureQueue();
+    active = new Map();
+    slotCounter = 0;
+    accountId;
+    defaultTimeoutMs;
+    /**
+     * Optional per-tenant scope (PRD-057 / S2 §8). When undefined, the
+     * governor behaves bit-identically to bridge's today. When set, the
+     * slot-key becomes `${accountId}:${appId}` and emitted observations
+     * carry the `appId` via the optional slot field.
+     */
+    appId;
+    constructor(config, onObservation, options) {
+        this.config = config;
+        this.onObservation = onObservation;
+        this.bucket = new TokenBucket({
+            burstCapacity: config.burstCapacity,
+            weeklyCap: config.weeklyCap,
+            concurrentCap: config.concurrentCap,
+        });
+        this.accountId = 'default';
+        this.defaultTimeoutMs = config.queueWaitTimeoutMs ?? 30_000;
+        this.appId = options?.appId;
+    }
+    async acquireSlot(opts) {
+        const timeoutMs = opts.timeoutMs;
+        // Fast path — try immediate acquisition
+        if (this.bucket.tryConsume()) {
+            return this.makeSlot(opts);
+        }
+        // Queue wait
+        try {
+            await this.queue.enqueue(timeoutMs, opts.abortSignal);
+        }
+        catch (err) {
+            // Translate queue errors into SaturationError for callers
+            const message = err.message;
+            if (message.includes('exceeded') || message.includes('Aborted')) {
+                throw new SaturationError(opts.providerClass, timeoutMs);
+            }
+            throw err;
+        }
+        // Try again after dequeue signal
+        if (this.bucket.tryConsume()) {
+            return this.makeSlot(opts);
+        }
+        throw new SaturationError(opts.providerClass, timeoutMs);
+    }
+    async releaseSlot(outcome) {
+        const record = this.active.get(outcome.slotId);
+        this.active.delete(outcome.slotId);
+        this.bucket.release();
+        // Signal next waiter
+        this.queue.dequeue();
+        // Emit observation callback
+        if (record) {
+            this.onObservation?.(outcome, record);
+        }
+    }
+    utilization(_providerClass, appIdFilter) {
+        // PRD-057 / S2 §8: when `appIdFilter` is supplied and this governor
+        // was constructed with a different `appId`, return empty (scope miss).
+        // When neither is supplied, or both match, return the bucket snapshot.
+        if (appIdFilter !== undefined && this.appId !== appIdFilter) {
+            return [];
+        }
+        const util = this.bucket.utilization();
+        const status = util.burstPct >= 100 || util.weeklyPct >= 100
+            ? 'saturated'
+            : 'ready';
+        return [{
+                accountId: this.accountId,
+                burstWindowUsedPct: util.burstPct,
+                weeklyUsedPct: util.weeklyPct,
+                inFlightCount: util.inFlight,
+                backpressureActive: this.queue.size > 0,
+                status,
+            }];
+    }
+    /** Expose the scoped `appId` (undefined = no scoping). */
+    getAppId() {
+        return this.appId;
+    }
+    activeSlots() {
+        return [...this.active.values()].map(r => r.slot);
+    }
+    /**
+     * Track the signature for a slot so releaseSlot can emit an observation.
+     * Called by the throttler/strategy layer after acquireSlot.
+     */
+    attachSignature(slotId, signature) {
+        const record = this.active.get(slotId);
+        if (record)
+            record.signature = signature;
+    }
+    /** Sweep leaked slots whose maxLifetimeMs has elapsed. */
+    sweep(onLeak) {
+        const now = Date.now();
+        const leaked = [];
+        for (const [slotId, record] of this.active) {
+            if (now - record.slot.acquiredAt > record.slot.maxLifetimeMs) {
+                leaked.push(record.slot);
+                this.active.delete(slotId);
+                this.bucket.release();
+                this.queue.dequeue();
+            }
+        }
+        for (const slot of leaked) {
+            onLeak?.(slot);
+        }
+        return leaked.length;
+    }
+    makeSlot(opts) {
+        const slotId = `slot-${++this.slotCounter}-${Date.now()}`;
+        const slot = {
+            slotId,
+            providerClass: opts.providerClass,
+            accountId: this.accountId,
+            acquiredAt: Date.now(),
+            estimatedCostUsd: opts.estimatedCostUsd,
+            maxLifetimeMs: 60_000,
+        };
+        this.active.set(slotId, { slot });
+        return slot;
+    }
+}
+//# sourceMappingURL=rate-governor-impl.js.map

package/dist/cost-governor/rate-governor-impl.js.map

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

package/dist/cost-governor/signature-builder.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Signature Builder — canonicalizes invocation parameters into
+ * an InvocationSignature for cost prediction lookups.
+ */
+import type { InvocationSignature } from '@methodts/types';
+export declare function inputSizeBucket(charCount: number): InvocationSignature['inputSizeBucket'];
+/**
+ * Build a canonical InvocationSignature from invocation parameters.
+ * Capabilities are sorted for stable hashing.
+ */
+export declare function buildSignature(params: {
+    methodologyId: string;
+    capabilities: readonly string[];
+    model: string;
+    promptCharCount: number;
+}): InvocationSignature;
+/**
+ * Produce a stable string hash for an InvocationSignature.
+ * Used as Map key for observation lookups.
+ */
+export declare function signatureKey(sig: InvocationSignature): string;
+//# sourceMappingURL=signature-builder.d.ts.map

package/dist/cost-governor/signature-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-builder.d.ts","sourceRoot":"","sources":["../../src/cost-governor/signature-builder.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAU3D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,GAChB,mBAAmB,CAAC,iBAAiB,CAAC,CAMxC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,mBAAmB,CAOtB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAE7D"}

package/dist/cost-governor/signature-builder.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Signature Builder — canonicalizes invocation parameters into
+ * an InvocationSignature for cost prediction lookups.
+ */
+/** Input size bucket thresholds (character count). */
+const SIZE_THRESHOLDS = {
+    xs: 1_000,
+    s: 10_000,
+    m: 100_000,
+    l: 1_000_000,
+};
+export function inputSizeBucket(charCount) {
+    if (charCount < SIZE_THRESHOLDS.xs)
+        return 'xs';
+    if (charCount < SIZE_THRESHOLDS.s)
+        return 's';
+    if (charCount < SIZE_THRESHOLDS.m)
+        return 'm';
+    if (charCount < SIZE_THRESHOLDS.l)
+        return 'l';
+    return 'xl';
+}
+/**
+ * Build a canonical InvocationSignature from invocation parameters.
+ * Capabilities are sorted for stable hashing.
+ */
+export function buildSignature(params) {
+    return {
+        methodologyId: params.methodologyId,
+        capabilities: [...params.capabilities].sort(),
+        model: params.model,
+        inputSizeBucket: inputSizeBucket(params.promptCharCount),
+    };
+}
+/**
+ * Produce a stable string hash for an InvocationSignature.
+ * Used as Map key for observation lookups.
+ */
+export function signatureKey(sig) {
+    return `${sig.methodologyId}|${sig.capabilities.join(',')}|${sig.model}|${sig.inputSizeBucket}`;
+}
+//# sourceMappingURL=signature-builder.js.map

package/dist/cost-governor/signature-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-builder.js","sourceRoot":"","sources":["../../src/cost-governor/signature-builder.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;GAGG;AAIH,sDAAsD;AACtD,MAAM,eAAe,GAAG;IACtB,EAAE,EAAE,KAAK;IACT,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,SAAS;CACJ,CAAC;AAEX,MAAM,UAAU,eAAe,CAC7B,SAAiB;IAEjB,IAAI,SAAS,GAAG,eAAe,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,SAAS,GAAG,eAAe,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9C,IAAI,SAAS,GAAG,eAAe,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9C,IAAI,SAAS,GAAG,eAAe,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAK9B;IACC,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,YAAY,EAAE,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE;QAC7C,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,eAAe,EAAE,eAAe,CAAC,MAAM,CAAC,eAAe,CAAC;KACzD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAwB;IACnD,OAAO,GAAG,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;AAClG,CAAC"}

package/dist/cost-governor/signature-builder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signature-builder.test.d.ts.map

package/dist/cost-governor/signature-builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-builder.test.d.ts","sourceRoot":"","sources":["../../src/cost-governor/signature-builder.test.ts"],"names":[],"mappings":""}