zuplo 7.7.8 → 7.7.10

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -27,13 +27,38 @@ The gateway owner remains in control:
 | `inboundPolicyChain` contains entries  | Entries run in the listed order      |
 | An entry has `enabled: false`          | That entry is skipped                |
 
-If a policy returns a response, that response is sent immediately and later
-entries do not run. If a chain is invalid, the request fails closed with an
-error that identifies the entry to fix.
+If a policy returns a response, later entries do not run. Successful 2xx
+responses still receive the budget check described below before they are sent.
+Other responses, including authentication failures, remain unchanged. If a chain
+is invalid, the request fails closed with an error that identifies the entry to
+fix.
 
 This inbound executor does not run `outboundPolicyChain`. That field is reserved
 for an outbound configuration executor on the response pipeline.
 
+## Automatic budget enforcement
+
+The executor enforces budgets configured on the application, its parent teams,
+and the gateway. This does not require a Metering policy and applies even when
+the application's policy chain is empty. An application cannot override a shared
+budget with a higher limit of its own.
+
+Request logs indicate when automatic budget checks run, including when the
+application has no Metering policy. Warnings identify exceeded budgets, blocked
+requests, fallback decisions, and checks that could not be completed.
+
+When a budget blocks a provider request, the gateway uses the configured quota
+fallback model or returns `429 Too Many Requests`. Successful responses from
+policies, including Semantic Cache hits, are also subject to budgets. A blocked
+response returns `429 Too Many Requests` without using a fallback model.
+Warning-only budgets do not block responses. Authentication failures and other
+non-2xx policy responses are preserved.
+
+Place Metering before Semantic Cache to count cache hits toward request limits.
+Budget changes can take time to take effect, and concurrent requests can exceed
+a budget before further requests are blocked. If a budget check is unavailable,
+requests can proceed unless a budget has already been determined to block them.
+
 ## Build an AI Gateway from scratch
 
 ### 1. Declare the policies
@@ -171,8 +196,7 @@ chain:
 }
 ```
 
-Routes that list only the executor keep working — the executor loads
-configuration when the channel is empty.
+If you omit the loader, the executor loads the application configuration.
 
 Authentication is optional and placement controls its scope:
 
@@ -205,14 +229,19 @@ An application can inherit the options from `policies.json`. Include
     {
       "name": "ai-gateway-metering-v2-inbound",
       "options": {
-        "limits": {
-          "requests": {
-            "daily": {
-              "enabled": true,
-              "limit": 1000
-            }
+        "budgetRules": [
+          {
+            "budgetBy": "app",
+            "meters": [
+              {
+                "meter": "requests",
+                "period": "daily",
+                "value": 1000,
+                "action": "block"
+              }
+            ]
           }
-        }
+        ]
       }
     },
     {
@@ -347,10 +376,10 @@ canonical forms when writing application configuration:
 | A key requiring brackets    | `request.user.data["team-id"]`              |
 
 The `expression` field contains the complete expression. Do not wrap it in an
-interpolation marker such as `${...}`. The runtime resolves it for every request
-after the application's inbound policy chain finishes. Updating an application's
-configuration changes which value later requests select without rebuilding or
-redeploying the gateway.
+interpolation marker such as `${...}`. Expressions use values from the request
+and context, including values set by earlier policies. Place policies that set
+these values before Semantic Cache. You can change an expression in the
+application configuration without rebuilding or redeploying the gateway.
 
 JSON encoding and expression syntax are separate. When writing raw JSON, escape
 the double quotes required by a bracket segment:
@@ -393,10 +422,8 @@ The selectable data model is:
 | `request` | `url`, `method`, `headers`, `user.sub`, `user.data`, `query`, `searchParams`, `params`, and the scalar Fetch request metadata `bodyUsed`, `cache`, `credentials`, `destination`, `integrity`, `keepalive`, `mode`, `redirect`, `referrer`, and `referrerPolicy` |
 | `context` | `contextId`, `requestId`, `custom`, `route`, and `incomingRequestProperties`                                                                                                                                                                                    |
 
-`request.body`, `context.log`, policy invocation methods, and every other host
-object are outside the selectable data model. The evaluator receives a
-plain-data snapshot of the selected root. It never receives the live request or
-context object.
+Expressions cannot read the request body, call logging or policy methods, or
+access properties outside this table.
 
 Expressions have these limits:
 
@@ -413,9 +440,8 @@ Expressions have these limits:
   It does not traverse arrays, class instances, inherited properties, or the
   property names `__proto__`, `constructor`, and `prototype`.
 
-Expressions observe values after the application's inbound policy chain
-finishes. An authentication policy can populate `request.user`. A custom policy
-earlier in the chain can derive a value and place it in a request header:
+An authentication policy can populate `request.user`. A custom policy earlier in
+the chain can derive a value and place it in a request header:
 
 ```ts
 import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
@@ -446,14 +472,12 @@ value to well-formed NFC Unicode and ignores it when it exceeds 256 UTF-8 bytes
 or contains control characters, U+2028, or U+2029. A missing or invalid value
 does not contribute to the rule for that request.
 
-The exact stored expression is the rule identity and analytics dimension name.
-Store its authored bytes unchanged. Different accepted spellings, such as single
-quotes and double quotes, identify different rules even when they select the
-same value.
+Use consistent spelling for each expression. Different spellings, such as single
+quotes and double quotes, identify different budget rules even when they select
+the same value.
 
-Malformed budget rules are logged and ignored individually. An unsupported
-expression is also logged and omitted from dimension capture and quota tokens;
-other valid rules continue to run.
+Invalid budget rules and unsupported expressions are logged and skipped. Other
+valid rules continue to apply.
 
 ## Write a custom policy for the chain
 

package/docs/policies/ai-gateway-fallback-model-v2-inbound/doc.md

@@ -70,9 +70,12 @@ not override. A configured `fallback` replaces an existing backup and timeout; a
 configured `quotaFallback` replaces an existing quota fallback.
 
 Retry and timeout fallback is available for translated Chat Completions and
-Embeddings requests. Native `/v1/messages` and `/v1/responses` requests are
-passed through without retrying a backup. Quota fallback remains a separate,
-metering-driven path.
+Embeddings requests. Native create requests at `/v1/messages` and
+`/v1/responses` use a compatible completions backup only after the primary
+exhausts its upstream 429 retries; they do not inherit `fallbackTimeoutSeconds`
+or transport/5xx fallback. Responses management operations do not retry a backup
+because stored response IDs belong to the provider that created them. Quota
+fallback remains a separate, metering-driven path.
 
 ## Write your own fallback policy
 

package/docs/policies/ai-gateway-metering-v2-inbound/doc.md

@@ -5,13 +5,19 @@ budgets before the provider request runs. It meters spend, tokens, and requests.
 Budget rules can cover the whole application or each distinct value of an
 expression.
 
-When a limit is exceeded, the policy activates the model selection's
-`quotaFallback` when AI Gateway Fallback Model supplied one. Otherwise it
-returns `429 Too Many Requests`.
+Application, team, and gateway budgets are enforced even when this policy is not
+included in the application's policy chain.
 
-Place Metering after Model Filtering and Fallback Model so an exceeded budget
-can activate the quota fallback. Put policies that may answer early, such as
-Semantic Cache, after Metering so cache hits still count toward request limits.
+Request logs indicate when automatic budget checks run and when a budget blocks
+a request or selects a fallback model.
+
+When a budget blocks a provider request, the gateway uses the configured quota
+fallback model or returns `429 Too Many Requests`. Cached responses are also
+subject to budgets: a blocked cache hit returns `429 Too Many Requests` without
+using a fallback model.
+
+Place Metering after Model Filtering and Fallback Model. Place it before
+Semantic Cache so cache hits count toward request limits.
 
 ## Example
 
@@ -62,19 +68,26 @@ value of its expression. An action of `"warn"` notifies without blocking. An
 action of `"block"` activates the configured quota fallback or returns
 `429 Too Many Requests` when usage reaches the value.
 
-> **Budgets fail open by default.** When `throwOnFailure` is `false`, a metering
-> service failure lets the request proceed unmetered and no limit is checked.
-> Set it to `true` to reject the request instead.
-
 ## Team limits
 
-Budgets configured on this application govern only this app. Limits configured
-on a parent team or the gateway root are enforced centrally after the
-application's policy chain, whether or not this policy appears in that chain. An
-inherited limit activates the selected model's quota fallback when available and
-otherwise returns `429 Too Many Requests`.
+Application budgets apply only to that application. Parent team and gateway
+budgets apply across their applications, even when an application does not
+include Metering. An application cannot override a shared budget with a higher
+limit of its own.
+
+For example, two applications that spend $40 and $10 exhaust their team's $50
+monthly budget. An application outside that team does not share its budget.
+
+Team policy templates provide defaults for application policies. To set a shared
+team budget, configure the budget on the team itself.
+
+## Budget availability
+
+Budget changes can take time to take effect. Usage is recorded asynchronously,
+so concurrent requests can exceed a budget before further requests are blocked.
 
-An application cannot disable inherited enforcement through its policy chain. If
-the central hierarchical check is unavailable, the request proceeds. The
-policy's `throwOnFailure` option controls failures while checking or recording
-the app's own limits; it does not change inherited-limit behavior.
+If a budget check is unavailable, requests can proceed unless a budget has
+already been determined to block them. The `throwOnFailure` option controls
+whether this policy rejects requests when its metering operations fail; it does
+not change how application, team, or gateway `budgetRules` handle unavailable
+checks.

package/docs/policies/ai-gateway-model-filtering-v2-inbound/doc.md

@@ -253,3 +253,58 @@ Policy order determines precedence:
 
 Prefer one policy as the primary selector so the route's intent is easy to
 understand.
+
+## Model discovery
+
+Authenticated `GET /v1/models` and `GET /v1/models/{providerName/model}` use the
+same app URL as inference. Select the inference endpoint with the optional
+`x-zuplo-models-endpoint` request header:
+
+| Value              | Eligible models                                                                                 | Response format |
+| ------------------ | ----------------------------------------------------------------------------------------------- | --------------- |
+| `chat-completions` | Active completion models supported by Chat Completions adapters, including existing translation | OpenAI          |
+| `messages`         | Active completion models supported by native Messages passthrough                               | Anthropic       |
+| `responses`        | Active completion models supported by the resolved Responses adapter                            | OpenAI          |
+| `embeddings`       | Active embedding models supported by the resolved embedding adapter                             | OpenAI          |
+
+An explicit header wins. Otherwise, the presence of `anthropic-version` selects
+`messages`; other requests default to `chat-completions`. Empty, unknown, and
+multiple selector values return an actionable 400. The selector affects
+discovery only. Embedding discovery is opt-in. Messages never translates to Chat
+Completions.
+
+Discovery applies the first Model Filtering policy's parsed rules, matching
+inference's selection precedence. A capability omitted from that policy lists no
+models. Without Model Filtering, discovery lists the eligible catalog. Inactive
+models, unavailable adapters, and assignments without locally resolvable
+credentials are excluded. List and retrieve use identical eligibility rules;
+unknown, filtered-out, and wrong-endpoint IDs return the same 404.
+
+IDs retain the exact model-name casing; only the provider assignment label is
+normalized. OpenAI entries contain `id`, `object`, `created`, and `owned_by`.
+`owned_by` means the provider assignment namespace, not the model's developer.
+Anthropic entries contain `id`, `type`, `display_name`, and `created_at`, with
+unknown required nullable metadata set to `null`. Unknown creation dates use the
+epoch; optional unknown metadata is omitted.
+
+OpenAI lists return every eligible model and ignore pagination parameters.
+Anthropic lists default to 20 entries, accept `limit` from 1–1000, and accept
+either `after_id` or `before_id` from a previous page. Follow `has_more` and
+`last_id` for forward pagination. Invalid cursors return 400; restart without a
+cursor.
+
+Discovery uses the existing 60-second catalog cache. An uncached lookup,
+including legacy fallback, has a two-second budget; failure returns a
+sanitized 503. A successfully loaded catalog with no eligible models returns an
+empty 200. Responses use `Cache-Control: private, no-store` and vary on both
+selector headers. Only GET is supported. POST, PUT, PATCH, DELETE, and HEAD
+return 405 with `Allow: GET`. OPTIONS is handled by the gateway’s existing CORS
+preflight handler before app routing.
+
+Authentication and general abuse protections still apply. Discovery skips prompt
+inspection, semantic caching, and inference-budget blocking, and records one
+baseline request. Eligibility describes the catalog, adapters, and declared
+filtering rules; it does not guarantee upstream availability, provider
+acceptance of credentials, or acceptance by prompt-dependent custom policies.
+Existing Chat Completions translation does not promise full feature parity. Keep
+a qualified model configured when a client's picker does not consume discovery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.7.8",
+  "version": "7.7.10",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.7.8",
-    "@zuplo/core": "7.7.8",
-    "@zuplo/runtime": "7.7.8",
-    "@zuplo/test": "7.7.8"
+    "@zuplo/cli": "7.7.10",
+    "@zuplo/core": "7.7.10",
+    "@zuplo/runtime": "7.7.10",
+    "@zuplo/test": "7.7.10"
   }
 }