@antseed/node 0.2.152 → 0.2.153

package/dist/payments/seller-free-tier-limiter.d.ts

@@ -1,22 +1,57 @@
 import { type FreeTierConsumption, type MeteringStorage } from '../metering/storage.js';
-export interface SellerFreeTierConfig {
+import { type FreeTierProgram, type FreeTierStakeTier } from './free-tier-program.js';
+import type { FreeTierStakeResolver, FreeTierStakeStanding } from './free-tier-stake-resolver.js';
+/** One free-tier program: base limits and the staked tiers above them. */
+export interface SellerFreeTierProgramConfig {
     /** Maximum zero-priced requests accepted from one buyer address per window. */
     maxRequestsPerAddress?: number;
     /** Maximum zero-priced requests accepted from one remote IP per window. */
     maxRequestsPerIp?: number;
     /** Sliding-window duration in milliseconds. Default: 24 hours. */
     windowMs?: number;
+    /**
+     * Larger allowances for buyers staked on this seller, by staking power.
+     * Default: `DEFAULT_FREE_TIER_STAKE_TIERS`. `[]` turns staked tiers off.
+     */
+    stakeTiers?: FreeTierStakeTier[];
+    /**
+     * Serve only buyers whose stake reaches a tier. The base limits are still
+     * required: they are the allowance the tier multipliers apply to.
+     */
+    stakersOnly?: boolean;
+}
+export interface SellerFreeTierConfig extends SellerFreeTierProgramConfig {
+    /**
+     * Programs for individual services, keyed by announced service id. A listed
+     * service uses only its own program and its own counters; the other
+     * zero-priced services use the seller-wide program above, or are not limited
+     * when there is none. On a priced service the program is a free allowance:
+     * requests it covers are served free, and the rest are paid as usual.
+     */
+    services?: Record<string, SellerFreeTierProgramConfig>;
 }
 export interface FreeTierDecision extends FreeTierConsumption {
     buyerAddress: string;
     /** Normalized remote IP the decision was keyed on, or null when unknown. */
     remoteIp: string | null;
+    /** Staked standing the decision used, or null for the base limits. */
+    standing: FreeTierStakeStanding | null;
+    /** Tier the standing earned under this program, or null for the base limits. */
+    tier: FreeTierStakeTier | null;
+    /** Limit that applied to the binding counter; null when unlimited. */
+    limit: number | null;
+    /** The program the request was decided under, as advertised. */
+    program: FreeTierProgram;
 }
 export interface FreeTierConsumeInput {
     buyerPeerId: string;
     service: string;
     /** Raw socket remote address of the buyer connection, if known. */
     remoteIp?: string | null;
+    /** Staked standing from `resolveStanding`; omitted or null applies the base limits. */
+    standing?: FreeTierStakeStanding | null;
+    /** The service is priced: only its own program applies, never the seller-wide one. */
+    paid?: boolean;
     nowMs?: number;
 }
 export declare const DEFAULT_FREE_TIER_WINDOW_MS: number;
@@ -27,17 +62,100 @@ export declare const DEFAULT_FREE_TIER_WINDOW_MS: number;
  */
 export declare function normalizeRemoteIp(remoteIp: string | null | undefined): string | null;
 export declare class SellerFreeTierLimiter {
-    readonly maxRequestsPerAddress: number | null;
-    readonly maxRequestsPerIp: number | null;
-    readonly windowMs: number;
+    private readonly _default;
+    private readonly _services;
+    /** Longest window of any program: usage younger than this is never pruned. */
+    private readonly _retentionMs;
     private readonly _storage;
     private readonly _inMemoryUsage;
+    private _stakeResolver;
+    private _chainId;
+    /** Last verified delegations per buyer address, in insertion order for eviction. */
+    private readonly _delegations;
+    /** Priced services, whose allowances never admit a free-usage channel. */
+    private _paidServices;
+    /** Zero-priced services this seller offers, or null when not told: they decide channel admission. */
+    private _freeServices;
     constructor(config: SellerFreeTierConfig, storage?: MeteringStorage | null);
+    /**
+     * @deprecated The seller-wide program's per-address limit, or null when it
+     * has none (including a limiter with only per-service programs). Use
+     * `program(service)` for the limits a service is served under.
+     */
+    get maxRequestsPerAddress(): number | null;
+    /** @deprecated The seller-wide program's per-IP limit, or null. Use `program(service)`. */
+    get maxRequestsPerIp(): number | null;
+    /** @deprecated The seller-wide program's window, else the default window. Use `program(service)`. */
+    get windowMs(): number;
+    /**
+     * Enable staked tiers. Without a resolver every buyer gets the base limits.
+     * `chainId` is the EIP-712 domain delegations are verified against.
+     */
+    setStakeResolver(resolver: FreeTierStakeResolver | null, chainId?: number): void;
+    /** Whether any program has staked tiers, so stake lookups are worth enabling. */
+    get hasStakeTiers(): boolean;
+    /** Whether staked tiers are live: configured and backed by on-chain reads. */
+    get stakeTiersActive(): boolean;
+    /**
+     * Whether a program applies to `service`: its own, or for a zero-priced
+     * service the seller-wide one. A priced service has one only when configured.
+     */
+    appliesTo(service: string, options?: {
+        paid?: boolean;
+    }): boolean;
+    /**
+     * Services that are priced. Their programs are free allowances on paid
+     * models, served without a free-usage channel, so channel admission ignores them.
+     */
+    setPaidServices(services: Iterable<string>): void;
+    /** The zero-priced services this seller offers, so channel admission checks exactly their programs. */
+    setFreeServices(services: Iterable<string>): void;
+    /**
+     * The program `service` is served under, or the seller-wide program when
+     * `service` is omitted; tiers only when they are enforced. Null when none applies.
+     */
+    program(service?: string, options?: {
+        paid?: boolean;
+    }): FreeTierProgram | null;
+    /**
+     * Peer-metadata capability strings advertising every program: the
+     * seller-wide one first, then services in id order. A program that would
+     * exceed `budget` strings is skipped whole, never advertised in part.
+     */
+    capabilities(budget?: number): string[];
+    /**
+     * Staked standing for this buyer, or null for the base limits. Never throws.
+     *
+     * `delegationsHeader` is the buyer's `x-antseed-free-tier-delegations`
+     * value (from a request or a free usage open), or '' when a request carried
+     * none. Verified stakers are remembered for the buyer, so an open from an
+     * older buyer, which passes undefined, sees the standing of its requests.
+     */
+    resolveStanding(buyerPeerId: string, delegationsHeader?: string): Promise<FreeTierStakeStanding | null>;
+    private _rememberDelegations;
+    /**
+     * One line per program: the seller-wide one for free models, then each
+     * service's own. A priced service's line is its free allowance before its
+     * price applies, as set by `setPaidServices`.
+     */
+    describePrograms(): string[];
     describe(): string;
+    /** Consume one request for `input.service`. Callers check `appliesTo` first. */
     consume(input: FreeTierConsumeInput): FreeTierDecision;
-    /** Check channel-open admission without consuming an inference request. */
-    check(input: Omit<FreeTierConsumeInput, 'service'>): FreeTierDecision;
+    /**
+     * Check channel-open admission without consuming an inference request.
+     * The channel serves every free service, so it is admitted when the program
+     * of some offered free service would still serve the buyer, or when one of
+     * them is not limited at all. Otherwise the first refusal (the seller-wide
+     * one when it applies) is reported. Without the offered services (see
+     * `setFreeServices`), every program of a zero-priced service is considered,
+     * and no seller-wide program means some free service is unlimited.
+     */
+    check(input: Omit<FreeTierConsumeInput, 'service' | 'paid'>): FreeTierDecision | null;
+    private _policies;
+    private _policyFor;
     private _evaluate;
+    private _bindingLimit;
     private _evaluateInMemory;
     private _pruneExpiredBuckets;
 }

package/dist/payments/seller-free-tier-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seller-free-tier-limiter.d.ts","sourceRoot":"","sources":["../../src/payments/seller-free-tier-limiter.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,mBAAmB,EAExB,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAGhC,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,2BAA2B,QAAmB,CAAC;AAG5D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAcpF;AAaD,qBAAa,qBAAqB;IAChC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;gBAElD,MAAM,EAAE,oBAAoB,EAAE,OAAO,GAAE,eAAe,GAAG,IAAW;IAsBhF,QAAQ,IAAI,MAAM;IAOlB,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,gBAAgB;IAItD,2EAA2E;IAC3E,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,GAAG,gBAAgB;IAIrE,OAAO,CAAC,SAAS;IAoBjB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,oBAAoB;CAO7B"}
+{"version":3,"file":"seller-free-tier-limiter.d.ts","sourceRoot":"","sources":["../../src/payments/seller-free-tier-limiter.ts"],"names":[],"mappings":"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"}

package/dist/payments/seller-free-tier-limiter.js

@@ -1,6 +1,9 @@
 import { isIP } from 'node:net';
 import { evaluateFreeTierLimits, } from '../metering/storage.js';
 import { peerIdToAddress } from '../types/peer.js';
+import { MAX_PEER_CAPABILITY_LENGTH } from '../discovery/metadata-validator.js';
+import { DEFAULT_FREE_TIER_STAKE_TIERS, encodeFreeTierCapabilities, freeTierStakeTierForPower, validateFreeTierStakeTiers, } from './free-tier-program.js';
+import { decodeFreeTierDelegationsHeader, verifyFreeTierDelegations, } from './free-tier-delegation.js';
 export const DEFAULT_FREE_TIER_WINDOW_MS = 24 * 60 * 60_000;
 const MAX_IN_MEMORY_KEYS = 20_000;
 /**
@@ -41,83 +44,390 @@ function expandIpv6(ip) {
     const zeros = isCompressed ? Array(missing).fill('0') : [];
     return [...headParts, ...zeros, ...tailParts].map((part) => part.padStart(4, '0'));
 }
-export class SellerFreeTierLimiter {
+/** One validated program and the counter scope it is accounted under. */
+class FreeTierPolicy {
+    scope;
     maxRequestsPerAddress;
     maxRequestsPerIp;
     windowMs;
-    _storage;
-    _inMemoryUsage = new Map();
-    constructor(config, storage = null) {
+    stakeTiers;
+    stakersOnly;
+    constructor(scope, config, label) {
+        this.scope = scope;
         const perAddress = config.maxRequestsPerAddress;
         const perIp = config.maxRequestsPerIp;
         if (perAddress !== undefined && (!Number.isSafeInteger(perAddress) || perAddress < 1)) {
-            throw new Error('freeTier.maxRequestsPerAddress must be a positive safe integer');
+            throw new Error(`${label}.maxRequestsPerAddress must be a positive safe integer`);
         }
         if (perIp !== undefined && (!Number.isSafeInteger(perIp) || perIp < 1)) {
-            throw new Error('freeTier.maxRequestsPerIp must be a positive safe integer');
+            throw new Error(`${label}.maxRequestsPerIp must be a positive safe integer`);
         }
         if (perAddress === undefined && perIp === undefined) {
-            throw new Error('freeTier requires maxRequestsPerAddress and/or maxRequestsPerIp');
+            throw new Error(`${label} requires maxRequestsPerAddress and/or maxRequestsPerIp`);
         }
         const windowMs = config.windowMs ?? DEFAULT_FREE_TIER_WINDOW_MS;
         if (!Number.isSafeInteger(windowMs) || windowMs < 1_000) {
-            throw new Error('freeTier.windowMs must be a safe integer of at least 1000');
+            throw new Error(`${label}.windowMs must be a safe integer of at least 1000`);
+        }
+        const stakeTiers = config.stakeTiers ?? DEFAULT_FREE_TIER_STAKE_TIERS;
+        validateFreeTierStakeTiers(stakeTiers, `${label}.stakeTiers`);
+        if (config.stakersOnly && stakeTiers.length === 0) {
+            throw new Error(`${label}.stakersOnly requires at least one stake tier`);
         }
         this.maxRequestsPerAddress = perAddress ?? null;
         this.maxRequestsPerIp = perIp ?? null;
         this.windowMs = windowMs;
-        this._storage = storage;
+        this.stakeTiers = Object.freeze([...stakeTiers]);
+        this.stakersOnly = config.stakersOnly === true;
+        // Peer metadata caps each capability string; a program that cannot be
+        // advertised would fail every metadata publish, so refuse it here.
+        const serviceId = scope === '' ? undefined : scope;
+        const encodings = [
+            encodeFreeTierCapabilities(this.program(true), serviceId),
+            ...(serviceId !== undefined ? [encodeFreeTierCapabilities(this.program(true), serviceId, { sellerWideTiers: this.stakeTiers })] : []),
+        ];
+        const tooLong = encodings.flat().find((capability) => capability.length > MAX_PEER_CAPABILITY_LENGTH);
+        if (tooLong) {
+            throw new Error(`${label} is too large to advertise ("${tooLong}" exceeds ${MAX_PEER_CAPABILITY_LENGTH} characters): lower its limits or window`);
+        }
     }
-    describe() {
+    program(tiersActive) {
+        return {
+            base: {
+                maxRequestsPerAddress: this.maxRequestsPerAddress,
+                maxRequestsPerIp: this.maxRequestsPerIp,
+                windowMs: this.windowMs,
+                ...(this.stakersOnly ? { stakersOnly: true } : {}),
+            },
+            stakeTiers: tiersActive ? [...this.stakeTiers] : [],
+        };
+    }
+    /** Requests per window a staked tier allows, or null when unlimited. */
+    limitForTier(tier) {
+        if (tier.multiplier === 'unlimited')
+            return null;
+        const base = this.maxRequestsPerAddress ?? this.maxRequestsPerIp;
+        return Math.min(Number.MAX_SAFE_INTEGER, base * tier.multiplier);
+    }
+    /**
+     * "free requests a day: 100 per buyer address, then paid; staked (a day):
+     * 1,000,000 power → 1,000, 10,000,000 power → unlimited". `paid`: the service is priced.
+     */
+    describe(paid = false) {
+        const window = describeWindow(this.windowMs);
         const parts = [];
         if (this.maxRequestsPerAddress !== null)
-            parts.push(`${this.maxRequestsPerAddress} per buyer address`);
+            parts.push(`${count(this.maxRequestsPerAddress)} per buyer address`);
         if (this.maxRequestsPerIp !== null)
-            parts.push(`${this.maxRequestsPerIp} per IP`);
-        return `${parts.join(', ')} every ${this.windowMs}ms`;
+            parts.push(`${count(this.maxRequestsPerIp)} per IP`);
+        const head = this.stakersOnly
+            ? `free only for stakers${paid ? ', others pay' : ', others are refused'}`
+            : `free requests ${window}: ${parts.join(', ')}${paid ? ', then paid' : ''}`;
+        const tiers = this.stakeTiers.map((tier) => {
+            const limit = this.limitForTier(tier);
+            return `${count(tier.minPower)} power → ${limit === null ? 'unlimited' : count(limit)}`;
+        });
+        return tiers.length > 0 ? `${head}; staked (${window}): ${tiers.join(', ')}` : head;
+    }
+}
+function count(value) {
+    return value.toLocaleString('en-US');
+}
+function describeWindow(windowMs) {
+    const hours = windowMs / 3_600_000;
+    if (hours === 24)
+        return 'a day';
+    if (hours >= 1 && Number.isInteger(hours))
+        return `per ${hours} h`;
+    return windowMs % 60_000 === 0 ? `per ${windowMs / 60_000} min` : `per ${windowMs / 1000} s`;
+}
+function hasSellerWideProgram(config) {
+    return config.maxRequestsPerAddress !== undefined
+        || config.maxRequestsPerIp !== undefined
+        || config.windowMs !== undefined
+        || config.stakeTiers !== undefined
+        || config.stakersOnly !== undefined;
+}
+export class SellerFreeTierLimiter {
+    _default;
+    _services;
+    /** Longest window of any program: usage younger than this is never pruned. */
+    _retentionMs;
+    _storage;
+    _inMemoryUsage = new Map();
+    _stakeResolver = null;
+    _chainId = 0;
+    /** Last verified delegations per buyer address, in insertion order for eviction. */
+    _delegations = new Map();
+    /** Priced services, whose allowances never admit a free-usage channel. */
+    _paidServices = new Set();
+    /** Zero-priced services this seller offers, or null when not told: they decide channel admission. */
+    _freeServices = null;
+    constructor(config, storage = null) {
+        const services = Object.entries(config.services ?? {});
+        if (!hasSellerWideProgram(config) && services.length === 0) {
+            throw new Error('freeTier requires maxRequestsPerAddress and/or maxRequestsPerIp');
+        }
+        this._default = hasSellerWideProgram(config) ? new FreeTierPolicy('', config, 'freeTier') : null;
+        this._services = new Map(services.map(([service, program]) => {
+            if (service.length === 0)
+                throw new Error('freeTier.services keys must be non-empty service ids');
+            return [service, new FreeTierPolicy(service, program, `freeTier.services.${service}`)];
+        }));
+        this._retentionMs = Math.max(...this._policies().map((policy) => policy.windowMs));
+        this._storage = storage;
+    }
+    /**
+     * @deprecated The seller-wide program's per-address limit, or null when it
+     * has none (including a limiter with only per-service programs). Use
+     * `program(service)` for the limits a service is served under.
+     */
+    get maxRequestsPerAddress() {
+        return this._default?.maxRequestsPerAddress ?? null;
+    }
+    /** @deprecated The seller-wide program's per-IP limit, or null. Use `program(service)`. */
+    get maxRequestsPerIp() {
+        return this._default?.maxRequestsPerIp ?? null;
+    }
+    /** @deprecated The seller-wide program's window, else the default window. Use `program(service)`. */
+    get windowMs() {
+        return this._default?.windowMs ?? DEFAULT_FREE_TIER_WINDOW_MS;
+    }
+    /**
+     * Enable staked tiers. Without a resolver every buyer gets the base limits.
+     * `chainId` is the EIP-712 domain delegations are verified against.
+     */
+    setStakeResolver(resolver, chainId = 0) {
+        this._stakeResolver = resolver;
+        this._chainId = chainId;
+    }
+    /** Whether any program has staked tiers, so stake lookups are worth enabling. */
+    get hasStakeTiers() {
+        return this._policies().some((policy) => policy.stakeTiers.length > 0);
     }
+    /** Whether staked tiers are live: configured and backed by on-chain reads. */
+    get stakeTiersActive() {
+        return this._stakeResolver !== null && this.hasStakeTiers;
+    }
+    /**
+     * Whether a program applies to `service`: its own, or for a zero-priced
+     * service the seller-wide one. A priced service has one only when configured.
+     */
+    appliesTo(service, options = {}) {
+        return this._policyFor(service, options.paid === true) !== null;
+    }
+    /**
+     * Services that are priced. Their programs are free allowances on paid
+     * models, served without a free-usage channel, so channel admission ignores them.
+     */
+    setPaidServices(services) {
+        this._paidServices = new Set(services);
+    }
+    /** The zero-priced services this seller offers, so channel admission checks exactly their programs. */
+    setFreeServices(services) {
+        this._freeServices = [...new Set(services)];
+    }
+    /**
+     * The program `service` is served under, or the seller-wide program when
+     * `service` is omitted; tiers only when they are enforced. Null when none applies.
+     */
+    program(service, options = {}) {
+        const policy = service === undefined ? this._default : this._policyFor(service, options.paid === true);
+        return policy?.program(this.stakeTiersActive) ?? null;
+    }
+    /**
+     * Peer-metadata capability strings advertising every program: the
+     * seller-wide one first, then services in id order. A program that would
+     * exceed `budget` strings is skipped whole, never advertised in part.
+     */
+    capabilities(budget = Number.POSITIVE_INFINITY) {
+        const active = this.stakeTiersActive;
+        const out = [];
+        const programs = [
+            ...(this._default ? [[undefined, this._default]] : []),
+            ...[...this._services].sort(([a], [b]) => a.localeCompare(b)),
+        ];
+        // Service programs may point at the seller-wide tiers only once those are advertised.
+        let sellerWideTiers;
+        for (const [service, policy] of programs) {
+            const strings = encodeFreeTierCapabilities(policy.program(active), service, sellerWideTiers ? { sellerWideTiers } : {});
+            if (out.length + strings.length > budget)
+                continue;
+            out.push(...strings);
+            if (service === undefined)
+                sellerWideTiers = policy.program(active).stakeTiers;
+        }
+        return out;
+    }
+    /**
+     * Staked standing for this buyer, or null for the base limits. Never throws.
+     *
+     * `delegationsHeader` is the buyer's `x-antseed-free-tier-delegations`
+     * value (from a request or a free usage open), or '' when a request carried
+     * none. Verified stakers are remembered for the buyer, so an open from an
+     * older buyer, which passes undefined, sees the standing of its requests.
+     */
+    async resolveStanding(buyerPeerId, delegationsHeader) {
+        if (!this._stakeResolver || !this.hasStakeTiers)
+            return null;
+        const buyer = peerIdToAddress(buyerPeerId).toLowerCase();
+        if (delegationsHeader !== undefined) {
+            const delegations = decodeFreeTierDelegationsHeader(delegationsHeader, buyer);
+            this._rememberDelegations(buyer, verifyFreeTierDelegations(delegations, buyer, this._chainId));
+        }
+        const nowSeconds = Date.now() / 1000;
+        const stakers = (this._delegations.get(buyer) ?? [])
+            .filter((delegation) => delegation.expiresAt > nowSeconds)
+            .map((delegation) => delegation.staker);
+        return this._stakeResolver.resolve(buyer, stakers);
+    }
+    _rememberDelegations(buyer, delegations) {
+        this._delegations.delete(buyer);
+        if (delegations.length === 0)
+            return;
+        if (this._delegations.size >= MAX_IN_MEMORY_KEYS) {
+            const oldest = this._delegations.keys().next().value;
+            if (oldest !== undefined)
+                this._delegations.delete(oldest);
+        }
+        this._delegations.set(buyer, delegations);
+    }
+    /**
+     * One line per program: the seller-wide one for free models, then each
+     * service's own. A priced service's line is its free allowance before its
+     * price applies, as set by `setPaidServices`.
+     */
+    describePrograms() {
+        const lines = this._default ? [`free models: ${this._default.describe()}`] : [];
+        for (const [service, policy] of this._services) {
+            lines.push(`${service}: ${policy.describe(this._paidServices.has(service))}`);
+        }
+        return lines;
+    }
+    describe() {
+        return this.describePrograms().join(' | ');
+    }
+    /** Consume one request for `input.service`. Callers check `appliesTo` first. */
     consume(input) {
-        return this._evaluate(input, input.service);
+        const policy = this._policyFor(input.service, input.paid === true);
+        if (!policy)
+            throw new Error(`no free-tier program applies to ${input.service}`);
+        return this._evaluate(policy, input, input.service);
     }
-    /** Check channel-open admission without consuming an inference request. */
+    /**
+     * Check channel-open admission without consuming an inference request.
+     * The channel serves every free service, so it is admitted when the program
+     * of some offered free service would still serve the buyer, or when one of
+     * them is not limited at all. Otherwise the first refusal (the seller-wide
+     * one when it applies) is reported. Without the offered services (see
+     * `setFreeServices`), every program of a zero-priced service is considered,
+     * and no seller-wide program means some free service is unlimited.
+     */
     check(input) {
-        return this._evaluate(input, null);
+        let policies;
+        if (this._freeServices) {
+            const applicable = this._freeServices.map((service) => this._policyFor(service, false));
+            if (applicable.length === 0 || applicable.some((policy) => policy === null))
+                return null;
+            policies = [...new Set(applicable)]
+                .sort((a, b) => (a === this._default ? -1 : b === this._default ? 1 : 0));
+        }
+        else {
+            if (!this._default)
+                return null;
+            policies = this._policies().filter((policy) => !this._paidServices.has(policy.scope));
+        }
+        const decisions = policies.map((policy) => this._evaluate(policy, input, null));
+        return decisions.find((decision) => decision.allowed) ?? decisions[0];
+    }
+    _policies() {
+        return [...(this._default ? [this._default] : []), ...this._services.values()];
     }
-    _evaluate(input, service) {
+    _policyFor(service, paid) {
+        return this._services.get(service) ?? (paid ? null : this._default);
+    }
+    _evaluate(policy, input, service) {
         const nowMs = input.nowMs ?? Date.now();
         const buyerAddress = peerIdToAddress(input.buyerPeerId).toLowerCase();
         const remoteIp = normalizeRemoteIp(input.remoteIp);
+        const program = policy.program(this.stakeTiersActive);
+        // A standing below this program's lowest tier gets the base limits.
+        const tier = input.standing ? freeTierStakeTierForPower(policy.stakeTiers, input.standing.power) : null;
+        const standing = tier ? input.standing : null;
+        if (policy.stakersOnly && !tier) {
+            return {
+                allowed: false,
+                remaining: 0,
+                retryAfterMs: 0,
+                limitedBy: 'stake_required',
+                buyerAddress,
+                remoteIp,
+                standing: input.standing ?? null,
+                tier: null,
+                limit: 0,
+                program,
+            };
+        }
+        const ownerLimit = tier ? policy.limitForTier(tier) : null;
         const usage = {
             buyerAddress,
             remoteIp,
-            maxRequestsPerAddress: this.maxRequestsPerAddress,
-            maxRequestsPerIp: this.maxRequestsPerIp,
-            windowMs: this.windowMs,
+            maxRequestsPerAddress: policy.maxRequestsPerAddress,
+            maxRequestsPerIp: policy.maxRequestsPerIp,
+            windowMs: policy.windowMs,
+            retentionMs: this._retentionMs,
+            scope: policy.scope,
             nowMs,
+            stake: standing ? { positionIds: standing.positionIds, limit: ownerLimit } : null,
         };
         const decision = this._storage
             ? (service === null
                 ? this._storage.checkFreeTierRequest(usage)
                 : this._storage.consumeFreeTierRequest({ ...usage, service }))
-            : this._evaluateInMemory(buyerAddress, remoteIp, nowMs, service !== null);
-        return { ...decision, buyerAddress, remoteIp };
+            : this._evaluateInMemory(policy, buyerAddress, remoteIp, standing, ownerLimit, nowMs, service !== null);
+        return {
+            ...decision,
+            buyerAddress,
+            remoteIp,
+            standing,
+            tier,
+            limit: this._bindingLimit(policy, decision, standing, ownerLimit),
+            program,
+        };
     }
-    _evaluateInMemory(buyerAddress, remoteIp, nowMs, consume) {
-        const windowStart = nowMs - this.windowMs;
+    _bindingLimit(policy, decision, standing, ownerLimit) {
+        if (standing)
+            return ownerLimit;
+        if (decision.limitedBy === 'ip')
+            return policy.maxRequestsPerIp;
+        return policy.maxRequestsPerAddress ?? policy.maxRequestsPerIp;
+    }
+    _evaluateInMemory(policy, buyerAddress, remoteIp, standing, ownerLimit, nowMs, consume) {
+        const windowStart = nowMs - policy.windowMs;
         const buckets = new Map();
         const checks = [];
         const track = (kind, key, limit) => {
-            const timestamps = (this._inMemoryUsage.get(key) ?? []).filter((timestamp) => timestamp >= windowStart);
-            buckets.set(key, timestamps);
+            const scopedKey = `${policy.scope}|${key}`;
+            const timestamps = (this._inMemoryUsage.get(scopedKey) ?? []).filter((timestamp) => timestamp >= windowStart);
+            buckets.set(scopedKey, timestamps);
             checks.push({ kind, limit, count: timestamps.length, oldestTimestamp: timestamps[0] ?? null });
         };
-        if (this.maxRequestsPerAddress !== null)
-            track('address', `address:${buyerAddress}`, this.maxRequestsPerAddress);
-        if (this.maxRequestsPerIp !== null && remoteIp !== null)
-            track('ip', `ip:${remoteIp}`, this.maxRequestsPerIp);
-        const decision = evaluateFreeTierLimits(checks, this.windowMs, nowMs);
+        if (standing) {
+            // Unlimited stake is not tracked: nothing would ever read the bucket.
+            if (ownerLimit !== null) {
+                for (const positionId of standing.positionIds)
+                    track('stake', `position:${positionId}`, ownerLimit);
+            }
+        }
+        else {
+            if (policy.maxRequestsPerAddress !== null)
+                track('address', `address:${buyerAddress}`, policy.maxRequestsPerAddress);
+            if (policy.maxRequestsPerIp !== null && remoteIp !== null)
+                track('ip', `ip:${remoteIp}`, policy.maxRequestsPerIp);
+        }
+        const decision = evaluateFreeTierLimits(checks, policy.windowMs, nowMs);
         if (decision.allowed && consume) {
-            this._pruneExpiredBuckets(windowStart);
+            this._pruneExpiredBuckets(nowMs - this._retentionMs);
             const newKeys = [...buckets.keys()].filter((key) => !this._inMemoryUsage.has(key)).length;
             if (this._inMemoryUsage.size + newKeys > MAX_IN_MEMORY_KEYS) {
                 throw new Error('free-tier limiter capacity reached while persistent metering is unavailable');