SMOODEV-2306: Add limits — the fourth @smooai/config kind

[brentrager]

Problem

@smooai/config has three kinds: publicConfigSchema, secretConfigSchema, featureFlagSchema. None fit a soft, tunable numeric target — a value that resolves differently per { orgId, agentId, plan, … }, flips without a redeploy, and carries its own clamp so a stale/bad server value can't push a consumer out of a safe range. Concretely, smooth-operator needs agentMaxIterations per {orgId, agentId} to replace the SMOOTH_AGENT_MAX_ITERATIONS env stopgap.

Solution — a numeric sibling of feature flags

Limits are the fourth kind: numeric, segment-resolved, clamp-aware, resolved live (never baked) through the SAME server segment evaluator as feature flags. A limit is a soft target — consuming code still hard-clamps; the config tunes within a client-applied [min, max]. No new resolution engine: the client code paths parallel the feature-flag evaluator exactly.

• Schema (TS): defineConfig({ limitsSchema }) + defineLimit({ default, min, max, step }), exposing LimitKeys + _limitsMeta, serialized as bounded JSON-Schema number nodes in the smooai-config push wire format. Limits stay out of the bake/env/file resolution chain (they never bake).
• Clamp (clampLimit, pure + identical in every language): non-finite/non-numeric → default; snap to step; clamp into [min, max]. Lives on the client so a stale server value can't escape the declared range.

Per-language surface

lang	evaluate	clamp	getLimit
TS	client.evaluateLimit(key, ctx?, env?) → EvaluateLimitResponse	clampLimit(raw, def)	config.limit.getLimit(key) / getClientLimit
Rust	client.evaluate_limit(key, ctx, env).await	clamp_limit(raw, &spec)	—
Python	client.evaluate_limit(key, ctx?, env?)	clamp_limit(raw, spec)	—
Go	client.EvaluateLimit(ctx, key, evalCtx, env)	ClampLimit(raw, spec)	—
.NET	client.EvaluateLimitAsync(key, ctx?, env?, ct)	spec.Clamp(raw)	—

Each with typed Limit* errors mirroring the feature-flag hierarchy (404/400/5xx). Also createLimitEvaluator factory + a limit tier (getLimit sync + evaluateLimit async, clamped) on buildClientConfig / buildConfig.

Endpoint contract: POST /organizations/{org_id}/config/limits/{key}/evaluate.

Test notes

Tests pass in all five languages:

• TS (vitest): full suite 288 passed; new schema/clamp + client evaluate + tier tests
• Rust (cargo): 289 passed; clippy -D warnings clean
• Python (pytest): 38 in test_client; ruff + basedpyright clean
• Go (go test): 353 passed; go vet clean
• .NET (xunit): 143 passed

pnpm typecheck + oxfmt --check + oxlint (0 errors) clean.

Known gaps (see DESIGN-limits.md)

1. Schema declaration is TS-only — limits are authored in TS .smooai-config and pushed; polyglot runtimes consume (evaluate) them, so native define_config signatures were left at three tiers.
2. Server endpoint — /config/limits/{key}/evaluate is documented + called here; wiring the route (alias to the numeric segment evaluator) is the smooai-monorepo follow-up.
3. Bundler baking of limit defaults + React useLimitEvaluation deferred (the latter waits on useFeatureFlagEvaluation, which never landed).

Docs: DESIGN-limits.md (full design + rollout), SCHEMA_USAGE.md (usage), changeset added. Links SMOODEV-2306.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 99d918a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@smooai/config	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR